< draft-ietf-core-comi-04.txt   draft-ietf-core-comi-05.txt >
CoRE M. Veillette, Ed. CoRE M. Veillette, Ed.
Internet-Draft Trilliant Networks Inc. Internet-Draft Trilliant Networks Inc.
Intended status: Standards Track P. van der Stok, Ed. Intended status: Standards Track P. van der Stok, Ed.
Expires: May 16, 2019 consultant Expires: November 16, 2019 consultant
A. Pelov A. Pelov
Acklio Acklio
A. Bierman A. Bierman
YumaWorks YumaWorks
November 12, 2018 May 15, 2019
CoAP Management Interface CoAP Management Interface
draft-ietf-core-comi-04 draft-ietf-core-comi-05
Abstract Abstract
This document describes a network management interface for This document describes a network management interface for
constrained devices and networks, called CoAP Management Interface constrained devices and networks, called CoAP Management Interface
(CoMI). The Constrained Application Protocol (CoAP) is used to (CoMI). The Constrained Application Protocol (CoAP) is used to
access datastore and data node resources specified in YANG, or SMIv2 access datastore and data node resources specified in YANG, or SMIv2
converted to YANG. CoMI uses the YANG to CBOR mapping and converts converted to YANG. CoMI uses the YANG to CBOR mapping and converts
YANG identifier strings to numeric identifiers for payload size YANG identifier strings to numeric identifiers for payload size
reduction. CoMI extends the set of YANG based protocols, NETCONF and reduction. The complete solution composed of CoMI,
[I-D.ietf-core-yang-cbor] and [I-D.ietf-core-sid] is called CORECONF.
CORECONF extends the set of YANG based protocols, NETCONF and
RESTCONF, with the capability to manage constrained devices and RESTCONF, with the capability to manage constrained devices and
networks. networks.
Note Note
Discussion and suggestions for improvement are requested, and should Discussion and suggestions for improvement are requested, and should
be sent to yot@ietf.org. be sent to yot@ietf.org.
Status of This Memo Status of This Memo
skipping to change at page 1, line 47 skipping to change at page 2, line 4
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 16, 2019.
This Internet-Draft will expire on May 16, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
skipping to change at page 2, line 34 skipping to change at page 2, line 35
2. CoMI Architecture . . . . . . . . . . . . . . . . . . . . . . 5 2. CoMI Architecture . . . . . . . . . . . . . . . . . . . . . . 5
2.1. Major differences between RESTCONF and CoMI . . . . . . . 6 2.1. Major differences between RESTCONF and CoMI . . . . . . . 6
2.2. Compression of YANG identifiers . . . . . . . . . . . . . 7 2.2. Compression of YANG identifiers . . . . . . . . . . . . . 7
2.3. Instance identifier . . . . . . . . . . . . . . . . . . . 8 2.3. Instance identifier . . . . . . . . . . . . . . . . . . . 8
2.4. Content-Formats . . . . . . . . . . . . . . . . . . . . . 8 2.4. Content-Formats . . . . . . . . . . . . . . . . . . . . . 8
2.5. Unified datastore . . . . . . . . . . . . . . . . . . . . 10 2.5. Unified datastore . . . . . . . . . . . . . . . . . . . . 10
3. Example syntax . . . . . . . . . . . . . . . . . . . . . . . 11 3. Example syntax . . . . . . . . . . . . . . . . . . . . . . . 11
4. CoAP Interface . . . . . . . . . . . . . . . . . . . . . . . 11 4. CoAP Interface . . . . . . . . . . . . . . . . . . . . . . . 11
4.1. Using the 'k' Uri-Query option . . . . . . . . . . . . . 13 4.1. Using the 'k' Uri-Query option . . . . . . . . . . . . . 13
4.2. Data Retrieval . . . . . . . . . . . . . . . . . . . . . 14 4.2. Data Retrieval . . . . . . . . . . . . . . . . . . . . . 14
4.2.1. Using the 'c' Uri-Query option . . . . . . . . . . . 15 4.2.1. Using the 'c' Uri-Query option . . . . . . . . . . . 14
4.2.2. Using the 'd' Uri-Query option . . . . . . . . . . . 15 4.2.2. Using the 'd' Uri-Query option . . . . . . . . . . . 15
4.2.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . 16 4.2.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.2.4. FETCH . . . . . . . . . . . . . . . . . . . . . . . . 19 4.2.4. FETCH . . . . . . . . . . . . . . . . . . . . . . . . 18
4.3. Data Editing . . . . . . . . . . . . . . . . . . . . . . 20 4.3. Data Editing . . . . . . . . . . . . . . . . . . . . . . 19
4.3.1. Data Ordering . . . . . . . . . . . . . . . . . . . . 20 4.3.1. Data Ordering . . . . . . . . . . . . . . . . . . . . 19
4.3.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 20 4.3.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 19
4.3.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 21 4.3.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 20
4.3.4. iPATCH . . . . . . . . . . . . . . . . . . . . . . . 22 4.3.4. iPATCH . . . . . . . . . . . . . . . . . . . . . . . 21
4.3.5. DELETE . . . . . . . . . . . . . . . . . . . . . . . 23 4.3.5. DELETE . . . . . . . . . . . . . . . . . . . . . . . 22
4.4. Full datastore access . . . . . . . . . . . . . . . . . . 23 4.4. Full datastore access . . . . . . . . . . . . . . . . . . 23
4.4.1. Full datastore examples . . . . . . . . . . . . . . . 24 4.4.1. Full datastore examples . . . . . . . . . . . . . . . 23
4.5. Event stream . . . . . . . . . . . . . . . . . . . . . . 25 4.5. Event stream . . . . . . . . . . . . . . . . . . . . . . 24
4.5.1. Notify Examples . . . . . . . . . . . . . . . . . . . 26 4.5.1. Notify Examples . . . . . . . . . . . . . . . . . . . 25
4.5.2. The 'f' Uri-Query option . . . . . . . . . . . . . . 26
4.6. RPC statements . . . . . . . . . . . . . . . . . . . . . 27 4.6. RPC statements . . . . . . . . . . . . . . . . . . . . . 27
4.6.1. RPC Example . . . . . . . . . . . . . . . . . . . . . 27 4.6.1. RPC Example . . . . . . . . . . . . . . . . . . . . . 27
5. Access to MIB Data . . . . . . . . . . . . . . . . . . . . . 28
6. Use of Block . . . . . . . . . . . . . . . . . . . . . . . . 28 5. Use of Block . . . . . . . . . . . . . . . . . . . . . . . . 29
7. Application Discovery . . . . . . . . . . . . . . . . . . . . 29 6. Application Discovery . . . . . . . . . . . . . . . . . . . . 29
7.1. YANG library . . . . . . . . . . . . . . . . . . . . . . 29 6.1. YANG library . . . . . . . . . . . . . . . . . . . . . . 29
7.2. Resource Discovery . . . . . . . . . . . . . . . . . . . 29 6.2. Resource Discovery . . . . . . . . . . . . . . . . . . . 30
7.2.1. Datastore Resource Discovery . . . . . . . . . . . . 30 6.2.1. Datastore Resource Discovery . . . . . . . . . . . . 30
7.2.2. Data node Resource Discovery . . . . . . . . . . . . 30 6.2.2. Data node Resource Discovery . . . . . . . . . . . . 30
7.2.3. Event stream Resource Discovery . . . . . . . . . . . 31 6.2.3. Event stream Resource Discovery . . . . . . . . . . . 31
8. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 31 7. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 31
9. Security Considerations . . . . . . . . . . . . . . . . . . . 34 8. Security Considerations . . . . . . . . . . . . . . . . . . . 35
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35
10.1. Resource Type (rt=) Link Target Attribute Values 9.1. Resource Type (rt=) Link Target Attribute Values Registry 35
Registry . . . . . . . . . . . . . . . . . . . . . . . . 35 9.2. CoAP Content-Formats Registry . . . . . . . . . . . . . . 36
10.2. CoAP Content-Formats Registry . . . . . . . . . . . . . 35 9.3. Media Types Registry . . . . . . . . . . . . . . . . . . 36
10.3. Media Types Registry . . . . . . . . . . . . . . . . . . 36 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 38
11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 37 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 38
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 38 11.1. Normative References . . . . . . . . . . . . . . . . . . 38
12.1. Normative References . . . . . . . . . . . . . . . . . . 38 11.2. Informative References . . . . . . . . . . . . . . . . . 40
12.2. Informative References . . . . . . . . . . . . . . . . . 39
Appendix A. ietf-comi YANG module . . . . . . . . . . . . . . . 40 Appendix A. ietf-comi YANG module . . . . . . . . . . . . . . . 40
Appendix B. ietf-comi .sid file . . . . . . . . . . . . . . . . 46 Appendix B. ietf-comi .sid file . . . . . . . . . . . . . . . . 46
Appendix C. YANG example specifications . . . . . . . . . . . . 49 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 49
C.1. ietf-system . . . . . . . . . . . . . . . . . . . . . . . 49
C.2. server list . . . . . . . . . . . . . . . . . . . . . . . 51
C.3. interfaces . . . . . . . . . . . . . . . . . . . . . . . 52
C.4. Example-port . . . . . . . . . . . . . . . . . . . . . . 52
C.5. IP-MIB . . . . . . . . . . . . . . . . . . . . . . . . . 53
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 55
1. Introduction 1. Introduction
The Constrained Application Protocol (CoAP) [RFC7252] is designed for The Constrained Application Protocol (CoAP) [RFC7252] is designed for
Machine to Machine (M2M) applications such as smart energy, smart Machine to Machine (M2M) applications such as smart energy, smart
city and building control. Constrained devices need to be managed in city and building control. Constrained devices need to be managed in
an automatic fashion to handle the large quantities of devices that an automatic fashion to handle the large quantities of devices that
are expected in future installations. Messages between devices need are expected in future installations. Messages between devices need
to be as small and infrequent as possible. The implementation to be as small and infrequent as possible. The implementation
complexity and runtime resources need to be as small as possible. complexity and runtime resources need to be as small as possible.
skipping to change at page 4, line 27 skipping to change at page 4, line 19
document are to be interpreted as described in [RFC2119]. document are to be interpreted as described in [RFC2119].
The following terms are defined in the YANG data modelling language The following terms are defined in the YANG data modelling language
[RFC7950]: action, anydata, anyxml, client, container, data model, [RFC7950]: action, anydata, anyxml, client, container, data model,
data node, identity, instance identifier, leaf, leaf-list, list, data node, identity, instance identifier, leaf, leaf-list, list,
module, RPC, schema node, server, submodule. module, RPC, schema node, server, submodule.
The following terms are defined in [RFC6241]: configuration data, The following terms are defined in [RFC6241]: configuration data,
datastore, state data datastore, state data
The following term is defined in [I-D.ietf-core-yang-cbor]: YANG The following term is defined in [I-D.ietf-core-sid]: YANG schema
schema item identifier (SID). item identifier (SID).
The following terms are defined in the CoAP protocol [RFC7252]: The following terms are defined in the CoAP protocol [RFC7252]:
Confirmable Message, Content-Format, Endpoint. Confirmable Message, Content-Format, Endpoint.
The following terms are defined in this document: The following terms are defined in this document:
data node resource: a CoAP resource that models a YANG data node. data node resource: a CoAP resource that models a YANG data node.
datastore resource: a CoAP resource that models a YANG datastore. datastore resource: a CoAP resource that models a YANG datastore.
skipping to change at page 6, line 27 skipping to change at page 6, line 20
unified datastore or multiple datastores as those defined by unified datastore or multiple datastores as those defined by
Network Management Datastore Architecture (NMDA) [RFC8342]. Network Management Datastore Architecture (NMDA) [RFC8342].
(6) Event stream: A resource used to get real time notifications. A (6) Event stream: A resource used to get real time notifications. A
CoMI server may support multiple Event streams serving different CoMI server may support multiple Event streams serving different
purposes such as normal monitoring, diagnostic, syslog, security purposes such as normal monitoring, diagnostic, syslog, security
monitoring. monitoring.
(7) Security: The server MUST prevent unauthorized users from (7) Security: The server MUST prevent unauthorized users from
reading or writing any CoMI resources. CoMI relies on security reading or writing any CoMI resources. CoMI relies on security
protocols such as DTLS [RFC6347] to secure CoAP communication. protocols such as DTLS [RFC6347] to secure CoAP communications.
2.1. Major differences between RESTCONF and CoMI 2.1. Major differences between RESTCONF and CoMI
CoMI is a RESTful protocol for small devices where saving bytes to CoMI is a RESTful protocol for small devices where saving bytes to
transport counts. Contrary to RESTCONF, many design decisions are transport counts. Contrary to RESTCONF, many design decisions are
motivated by the saving of bytes. Consequently, CoMI is not a motivated by the saving of bytes. Consequently, CoMI is not a
RESTCONF over CoAP protocol, but differs more significantly from RESTCONF over CoAP protocol, but differs more significantly from
RESTCONF. Some major differences are cited below: RESTCONF. Some major differences are cited below:
o CoMI uses CoAP/UDP as transport protocol and CBOR as payload o CoMI uses CoAP/UDP as transport protocol and CBOR as payload
skipping to change at page 6, line 49 skipping to change at page 6, line 42
transport protocol and JSON or XML as payload formats. transport protocol and JSON or XML as payload formats.
o CoMI encodes YANG identifier strings as numbers, where RESTCONF o CoMI encodes YANG identifier strings as numbers, where RESTCONF
does not. does not.
o CoMI uses the methods FETCH and iPATCH to access multiple data o CoMI uses the methods FETCH and iPATCH to access multiple data
nodes. RESTCONF uses instead the HTTP method PATCH and the HTTP nodes. RESTCONF uses instead the HTTP method PATCH and the HTTP
method GET with the "fields" Query parameter. method GET with the "fields" Query parameter.
o RESTCONF uses the HTTP methods HEAD, and OPTIONS, which are not o RESTCONF uses the HTTP methods HEAD, and OPTIONS, which are not
used by CoAP. supported by CoAP.
o CoMI does not support "insert" query parameter (first, last, o CoMI does not support "insert" query parameter (first, last,
before, after) and the "point" query parameter which are supported before, after) and the "point" query parameter which are supported
by RESTCONF. by RESTCONF.
o CoMI does not support the "start-time" and "stop-time" query o CoMI does not support the "start-time" and "stop-time" query
parameters to retrieve past notifications. parameters to retrieve past notifications.
o CoMI does not support the "filter" query parameters to observe a o CoMI does not support the "filter" query parameters to observe a
specific set of notifications. specific set of notifications.
skipping to change at page 9, line 26 skipping to change at page 9, line 10
application/yang-instances+cbor: This Content-Format represents a application/yang-instances+cbor: This Content-Format represents a
CBOR YANG document containing a list of data node instances. Each CBOR YANG document containing a list of data node instances. Each
data node instance is identified by its associated instance data node instance is identified by its associated instance
identifier. identifier.
FORMAT: CBOR array of CBOR map of instance-identifier, instance- FORMAT: CBOR array of CBOR map of instance-identifier, instance-
value value
The message payload of Content-Format 'application/yang- The message payload of Content-Format 'application/yang-
instances+cbor' is encoded using a CBOR array. Each entry within instances+cbor' is encoded using a CBOR array. Each entry within
this CBOR array contains a CBOR map carrying a single instance this CBOR array contains a CBOR map carrying an instance
identifier and associated value. Instance identifiers are encoded identifier and associated instance value. Instance identifiers
using the rules defined in [I-D.ietf-core-yang-cbor] section are encoded using the rules defined in [I-D.ietf-core-yang-cbor]
6.13.1, values are encoded using the rules defined in section 6.13.1, values are encoded using the rules defined in
[I-D.ietf-core-yang-cbor] section 4. [I-D.ietf-core-yang-cbor] section 4.
When present in an iPATCH request payload, this Content-Format When present in an iPATCH request payload, this Content-Format
carry a list of data node instances to be replaced, created, or carry a list of data node instances to be replaced, created, or
deleted. For each data node instance D, for which the instance deleted. For each data node instance D, for which the instance
identifier is the same as a data node instance I, in the targeted identifier is the same as a data node instance I, in the targeted
datastore resource: the value of D replaces the value of I. When datastore resource: the value of D replaces the value of I. When
the value of D is null, the data node instance I is removed. When the value of D is null, the data node instance I is removed. When
the targeted datastore resource does not contain a data node the targeted datastore resource does not contain a data node
instance with the same instance identifier as D, a new instance is instance with the same instance identifier as D, a new instance is
created with the same instance identifier and value as D. created with the same instance identifier and value as D.
The different Content-formats usage are summarized in the table The different Content-format usages are summarized in the table
below: below:
+---------------+--------------+------------------------------------+ +---------------+--------------+------------------------------------+
| Method | Resource | Content-Format | | Method | Resource | Content-Format |
+---------------+--------------+------------------------------------+ +---------------+--------------+------------------------------------+
| GET response | data node | /application/yang-data+cbor | | GET response | data node | /application/yang-data+cbor |
| | | | | | | |
| PUT request | data node | /application/yang-data+cbor | | PUT request | data node | /application/yang-data+cbor |
| | | | | | | |
| POST request | data node | /application/yang-data+cbor | | POST request | data node | /application/yang-data+cbor |
skipping to change at page 10, line 39 skipping to change at page 10, line 39
| | | | | | | |
| GET response | event stream | /application/yang-instances+cbor | | GET response | event stream | /application/yang-instances+cbor |
| | | | | | | |
| POST request | rpc, action | /application/yang-data+cbor | | POST request | rpc, action | /application/yang-data+cbor |
| | | | | | | |
| POST response | rpc, action | /application/yang-data+cbor | | POST response | rpc, action | /application/yang-data+cbor |
+---------------+--------------+------------------------------------+ +---------------+--------------+------------------------------------+
2.5. Unified datastore 2.5. Unified datastore
CoMI supports a simple datastore model consisting of on a single CoMI supports a simple datastore model consisting of a single unified
unified datastore. This datasore provides access to both datastore. This datasore provides access to both configuration and
configuration and operational data. Configuration updates performed operational data. Configuration updates performed on this datastore
on this datastore are reflected immediately or with a minimal delay are reflected immediately or with a minimal delay as operational
as operational data. data.
Alternatively, CoMI servers MAY implement a more complex datastore Alternatively, CoMI servers MAY implement a more complex datastore
model such as the Network Management Datastore Architecture (NMDA) as model such as the Network Management Datastore Architecture (NMDA) as
defined by [RFC8342]. Each datastore supported is implemented as a defined by [RFC8342]. Each datastore supported is implemented as a
datastore resource. datastore resource.
Characteristics of the unified datastore are summarized in the table Characteristics of the unified datastore are summarized in the table
below: below:
+-------------+-----------------------------------------------------+ +-------------+-----------------------------------------------------+
skipping to change at page 11, line 20 skipping to change at page 11, line 20
| YANG | all modules | | YANG | all modules |
| modules | | | modules | |
| | | | | |
| YANG nodes | all data nodes ("config true" and "config false") | | YANG nodes | all data nodes ("config true" and "config false") |
| | | | | |
| Access | read-write | | Access | read-write |
| | | | | |
| How applied | changes applied in place immediately or with a | | How applied | changes applied in place immediately or with a |
| | minimal delay | | | minimal delay |
| | | | | |
| Protocols | CoMI | | Protocols | CORECONF |
| | | | | |
| Defined in | "ietf-comi" | | Defined in | "ietf-comi" |
+-------------+-----------------------------------------------------+ +-------------+-----------------------------------------------------+
3. Example syntax 3. Example syntax
This section presents the notation used for the examples. The YANG
modules that are used throughout this document are shown in
Appendix C. The example modules are copied from existing modules and
annotated with SIDs.
CBOR is used to encode CoMI request and response payloads. The CBOR CBOR is used to encode CoMI request and response payloads. The CBOR
syntax of the YANG payloads is specified in [RFC7049]. The payload syntax of the YANG payloads is specified in [RFC7049]. The payload
examples are notated in Diagnostic notation (defined in section 6 of examples are notated in Diagnostic notation (defined in section 6 of
[RFC7049]) that can be automatically converted to CBOR. [RFC7049]) that can be automatically converted to CBOR.
SIDs in URIs are represented as a base64 number, SIDs in the payload SIDs in URIs are represented as a base64 number, SIDs in the payload
are represented as decimal numbers. are represented as decimal numbers.
4. CoAP Interface 4. CoAP Interface
This note specifies a Management Interface. CoAP endpoints that This note specifies a Management Interface. CoAP endpoints that
implement the CoMI management protocol, support at least one implement the CoMI management protocol, support at least one
discoverable management resource of resource type (rt): core.c.ds, discoverable management resource of resource type (rt): core.c.ds,
with example path: /c, where c is short-hand for CoMI. The path /c with example path: /c, where c is short-hand for CoMI. The path /c
is recommended, but not compulsory (see Section 7). is recommended, but not compulsory (see Section 6).
The mapping of YANG data node instances to CoMI resources is as The mapping of YANG data node instances to CoMI resources is as
follows. Every data node of the YANG modules loaded in the CoMI follows. Every data node of the YANG modules loaded in the CoMI
server represents a sub-resource of the datastore resource (e.g. /c/ server represents a sub-resource of the datastore resource (e.g. /c/
sid). When multiple instances of a list exist, instance selection is sid). When multiple instances of a list exist, instance selection is
possible as described in Section 4.1, Section 4.2.3.1, and possible as described in Section 4.1, Section 4.2.3.1, and
Section 4.2.4. Section 4.2.4.
CoMI also supports event stream resourced used to observe CoMI also supports event stream resourced used to observe
notification instances. Event stream resources can be discovered notification instances. Event stream resources can be discovered
skipping to change at page 13, line 10 skipping to change at page 13, line 4
+-----------+-------------------------------------------------------+ +-----------+-------------------------------------------------------+
There is one Uri-Query option for the GET, PUT, POST, and DELETE There is one Uri-Query option for the GET, PUT, POST, and DELETE
methods. methods.
+------------------+----------------------------------------+ +------------------+----------------------------------------+
| Uri-Query option | Description | | Uri-Query option | Description |
+------------------+----------------------------------------+ +------------------+----------------------------------------+
| k | Select an instance within YANG list(s) | | k | Select an instance within YANG list(s) |
+------------------+----------------------------------------+ +------------------+----------------------------------------+
This parameter is not used for FETCH and iPATCH, because their This parameter is not used for FETCH and iPATCH, because their
request payloads support list instance selection. request payloads support list instance selection.
4.1. Using the 'k' Uri-Query option 4.1. Using the 'k' Uri-Query option
The "k" (key) parameter specifies a specific instance of a data node. 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 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 identifies a data node, and key1, key2 are the values of the key
leaves that specify an instance. Lists can have multiple keys, and leaves that specify an instance. Lists can have multiple keys, and
lists can be part of lists. The order of key value generation is lists can be part of lists. The order of key value generation is
given recursively by: given recursively by:
o For a given list, if a parent data node is a list, generate the o For a given list, if a parent data node is a list, generate the
keys for the parent list first. keys for the parent list first.
o For a given list, generate key values in the order specified in o For a given list, generate key values in the order specified in
the YANG module. the YANG module.
skipping to change at page 15, line 5 skipping to change at page 14, line 25
The resulting key string is encoded in a Uri-Query as specified in The resulting key string is encoded in a Uri-Query as specified in
[RFC7252] section 6.5. [RFC7252] section 6.5.
4.2. Data Retrieval 4.2. Data Retrieval
One or more data nodes can be retrieved by the client. The operation 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 [RFC7252] and is mapped to the GET method defined in section 5.8.1 of [RFC7252] and
to the FETCH method defined in section 2 of [RFC8132]. to the FETCH method defined in section 2 of [RFC8132].
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 [RFC7959]
may be used, as explained in more detail in Section 6.
There are two additional Uri-Query options for the GET and FETCH There are two additional Uri-Query options for the GET and FETCH
methods. methods.
+-------------+-----------------------------------------------------+ +-------------+-----------------------------------------------------+
| Uri-Query | Description | | Uri-Query | Description |
| option | | | option | |
+-------------+-----------------------------------------------------+ +-------------+-----------------------------------------------------+
| c | Control selection of configuration and non- | | c | Control selection of configuration and non- |
| | configuration data nodes (GET and FETCH) | | | configuration data nodes (GET and FETCH) |
| | | | | |
| d | Control retrieval of default values. | | d | Control retrieval of default values. |
+-------------+-----------------------------------------------------+ +-------------+-----------------------------------------------------+
4.2.1. Using the 'c' Uri-Query option 4.2.1. Using the 'c' Uri-Query option
The 'c' (content) parameter controls how descendant nodes of the The 'c' (content) option controls how descendant nodes of the
requested data nodes will be processed in the reply. requested data nodes will be processed in the reply.
The allowed values are: The allowed values are:
+-------+-----------------------------------------------------+ +-------+-----------------------------------------------------+
| Value | Description | | Value | Description |
+-------+-----------------------------------------------------+ +-------+-----------------------------------------------------+
| c | Return only configuration descendant data nodes | | c | Return only configuration descendant data nodes |
| | | | | |
| n | Return only non-configuration descendant data nodes | | n | Return only non-configuration descendant data nodes |
| | | | | |
| a | Return all descendant data nodes | | a | Return all descendant data nodes |
+-------+-----------------------------------------------------+ +-------+-----------------------------------------------------+
This parameter is only allowed for GET and FETCH methods on datastore This option is only allowed for GET and FETCH methods on datastore
and data node resources. A 4.02 (Bad Option) error is returned if and data node resources. A 4.02 (Bad Option) error is returned if
used for other methods or resource types. used for other methods or resource types.
If this Uri-Query option is not present, the default value is "a". If this Uri-Query option is not present, the default value is "a".
4.2.2. Using the 'd' Uri-Query option 4.2.2. Using the 'd' Uri-Query option
The "d" (with-defaults) parameter controls how the default values of The "d" (with-defaults) option controls how the default values of the
the descendant nodes of the requested data nodes will be processed. descendant nodes of the requested data nodes will be processed.
The allowed values are: The allowed values are:
+-------+-----------------------------------------------------------+ +-------+-----------------------------------------------------------+
| Value | Description | | Value | Description |
+-------+-----------------------------------------------------------+ +-------+-----------------------------------------------------------+
| a | All data nodes are reported. Defined as 'report-all' in | | a | All data nodes are reported. Defined as 'report-all' in |
| | section 3.1 of [RFC6243]. | | | section 3.1 of [RFC6243]. |
| | | | | |
| t | Data nodes set to the YANG default are not reported. | | t | Data nodes set to the YANG default are not reported. |
skipping to change at page 16, line 47 skipping to change at page 16, line 22
GET /c/instance-identifier GET /c/instance-identifier
2.05 Content (Content-Format: application/yang-data+cbor) 2.05 Content (Content-Format: application/yang-data+cbor)
CBOR map of SID, instance-value CBOR map of SID, instance-value
The returned payload contains the CBOR encoding of the specified data The returned payload contains the CBOR encoding of the specified data
node instance value. node instance value.
4.2.3.1. GET Examples 4.2.3.1. GET Examples
Using for example the current-datetime leaf from Appendix C.1, a Using for example the current-datetime leaf from module ietf-system
request is sent to retrieve the value of 'system-state/clock/current- [RFC7317], a request is sent to retrieve the value of 'system-
datetime' specified in container system-state. The SID of 'system- state/clock/current-datetime' specified in container system-state.
state/clock/current-datetime' is 1723, encoded in base64 according to The SID of 'system-state/clock/current-datetime' is 1723, encoded in
Section 2.2, yields a7. The response to the request returns the CBOR base64 according to Section 2.2, yields a7. The response to the
map with the key set to the SID of the requested data node (i.e. request returns the CBOR map with the key set to the SID of the
requested data node (i.e. 1723) and the value encoded using a 'text
1723) and the value encoded using a 'text string' as defined in string' as defined in [I-D.ietf-core-yang-cbor] section 6.4.
[I-D.ietf-core-yang-cbor] section 6.4.
REQ: GET example.com/c/a7 REQ: GET example.com/c/a7
RES: 2.05 Content (Content-Format: application/yang-data+cbor) RES: 2.05 Content (Content-Format: application/yang-data+cbor)
{ {
1723 : "2014-10-26T12:16:31Z" 1723 : "2014-10-26T12:16:31Z"
} }
The next example represents the retrieval of a YANG container. In The next example represents the retrieval of a YANG container. In
this case, the CoMI client performs a GET request on the clock this case, the CoMI client performs a GET request on the clock
skipping to change at page 18, line 47 skipping to change at page 18, line 4
1533 : [ 1533 : [
{ {
+4 : "eth0", / name (SID 1537) / +4 : "eth0", / name (SID 1537) /
+1 : "Ethernet adaptor", / description (SID 1534) / +1 : "Ethernet adaptor", / description (SID 1534) /
+5 : 1880, / type, (SID 1538) identity / +5 : 1880, / type, (SID 1538) identity /
/ ethernetCsmacd (SID 1880) / / ethernetCsmacd (SID 1880) /
+2 : true / enabled ( SID 1535) / +2 : true / enabled ( SID 1535) /
} }
] ]
} }
It is equally possible to select a leaf of a specific instance of a It is equally possible to select a leaf of a specific instance of a
list. The example below requests the description leaf (SID=1534, list. The example below requests the description leaf (SID=1534,
base64: X-) within the interface list corresponding to the interface base64: X-) within the interface list corresponding to the interface
name "eth0". The returned value is encoded in CBOR based on the name "eth0". The returned value is encoded in CBOR based on the
rules specified by [I-D.ietf-core-yang-cbor] section 5.4. rules specified by [I-D.ietf-core-yang-cbor] section 6.4.
REQ: GET example.com/c/X-?k="eth0" REQ: GET example.com/c/X-?k="eth0"
RES: 2.05 Content (Content-Format: application/yang-data+cbor) RES: 2.05 Content (Content-Format: application/yang-data+cbor)
{ {
1534 : "Ethernet adaptor" 1534 : "Ethernet adaptor"
} }
4.2.4. FETCH 4.2.4. FETCH
skipping to change at page 19, line 37 skipping to change at page 18, line 42
FORMAT: FORMAT:
FETCH /c (Content-Format: application/yang-identifiers+cbor) FETCH /c (Content-Format: application/yang-identifiers+cbor)
CBOR array of instance-identifier CBOR array of instance-identifier
2.05 Content (Content-Format: application/yang-instances+cbor) 2.05 Content (Content-Format: application/yang-instances+cbor)
CBOR array of CBOR map of instance-identifier, instance-value CBOR array of CBOR map of instance-identifier, instance-value
4.2.4.1. FETCH examples 4.2.4.1. FETCH examples
This example uses the current-datetime leaf and the interface list This example uses the current-datetime leaf from module ietf-system
from Appendix C.1. In this example the value of current-datetime [RFC7317] and the interface list from module ietf-interfaces
(SID 1723) and the interface list (SID 1533) instance identified with [RFC7223]. In this example the value of current-datetime (SID 1723)
and the interface list (SID 1533) instance identified with
name="eth0" are queried. name="eth0" are queried.
REQ: FETCH /c (Content-Format: application/yang-identifiers+cbor) REQ: FETCH /c (Content-Format: application/yang-identifiers+cbor)
[ [
1723, / current-datetime (SID 1723) / 1723, / current-datetime (SID 1723) /
[1533, "eth0"] / interface (SID 1533) with name = "eth0" / [1533, "eth0"] / interface (SID 1533) with name = "eth0" /
] ]
RES: 2.05 Content (Content-Format: application/yang-instances+cbor) RES: 2.05 Content (Content-Format: application/yang-instances+cbor)
[ [
skipping to change at page 21, line 17 skipping to change at page 20, line 17
(Content-Format :application/yang-data+cbor) (Content-Format :application/yang-data+cbor)
CBOR map of SID, instance-value CBOR map of SID, instance-value
2.01 Created 2.01 Created
If the data node resource already exists, then the POST request MUST If the data node resource already exists, then the POST request MUST
fail and a "4.09 Conflict" response code MUST be returned fail and a "4.09 Conflict" response code MUST be returned
4.3.2.1. Post example 4.3.2.1. Post example
The example uses the interface list from Appendix C.1. Example is The example uses the interface list from module ietf-interfaces
creating a new list instance within the interface list (SID = 1533): [RFC7223]. This example creates a new list instance within the
interface list (SID = 1533):
REQ: POST /c/X9 (Content-Format: application/yang-data+cbor) REQ: POST /c/X9 (Content-Format: application/yang-data+cbor)
{ {
1533 : [ 1533 : [
{ {
+4 : "eth5", / name (SID 1537) / +4 : "eth5", / name (SID 1537) /
+1 : "Ethernet adaptor", / description (SID 1534) / +1 : "Ethernet adaptor", / description (SID 1534) /
+5 : 1880, / type (SID 1538), identity / +5 : 1880, / type (SID 1538), identity /
/ ethernetCsmacd (SID 1880) / / ethernetCsmacd (SID 1880) /
+2 : true / enabled (SID 1535) / +2 : true / enabled (SID 1535) /
skipping to change at page 21, line 50 skipping to change at page 21, line 7
FORMAT: FORMAT:
PUT /c/<instanceidentifier> PUT /c/<instanceidentifier>
(Content-Format :application/yang-data+cbor) (Content-Format :application/yang-data+cbor)
CBOR map of SID, instance-value CBOR map of SID, instance-value
2.01 Created 2.01 Created
4.3.3.1. PUT example 4.3.3.1. PUT example
The example uses the interface list from Appendix C.1. Example is The example uses the interface list from module ietf-interfaces
renewing an instance of the list interface (SID = 1533) with key [RFC7223]. Example updates the instance of the list interface (SID =
name="eth0": 1533) with key name="eth0":
REQ: PUT /c/X9?k="eth0" (Content-Format: application/yang-data+cbor) REQ: PUT /c/X9?k="eth0" (Content-Format: application/yang-data+cbor)
{ {
1533 : [ 1533 : [
{ {
+4 : "eth0", / name (SID 1537) / +4 : "eth0", / name (SID 1537) /
+1 : "Ethernet adaptor", / description (SID 1534) / +1 : "Ethernet adaptor", / description (SID 1534) /
+5 : 1880, / type (SID 1538), identity / +5 : 1880, / type (SID 1538), identity /
/ ethernetCsmacd (SID 1880) / / ethernetCsmacd (SID 1880) /
+2 : true / enabled (SID 1535) / +2 : true / enabled (SID 1535) /
} }
] ]
} }
RES: 2.04 Changed RES: 2.04 Changed
4.3.4. iPATCH 4.3.4. iPATCH
One or multiple data node instances are replaced with the idempotent One or multiple data node instances are replaced with the idempotent
iPATCH method [RFC8132]. A request is sent with a CoAP iPATCH CoAP iPATCH method [RFC8132].
message.
There are no Uri-Query options for the iPATCH method. There are no Uri-Query options for the iPATCH method.
The processing of the iPATCH command is specified by Content-Format The processing of the iPATCH command is specified by Content-Format
'application/yang-instances+cbor'. In summary, if the CBOR patch 'application/yang-instances+cbor'. In summary, if the CBOR patch
payload contains a data node instance that is not present in the payload contains a data node instance that is not present in the
target, this instance is added. If the target contains the specified target, this instance is added. If the target contains the specified
instance, the content of this instance is replaced with the value of instance, the content of this instance is replaced with the value of
the payload. A null value indicates the removal of an existing data the payload. A null value indicates the removal of an existing data
node instance. node instance.
skipping to change at page 23, line 37 skipping to change at page 22, line 43
A data node resource is deleted with the DELETE method. A data node resource is deleted with the DELETE method.
FORMAT: FORMAT:
Delete /c/<instance identifier> Delete /c/<instance identifier>
2.02 Deleted 2.02 Deleted
4.3.5.1. DELETE example 4.3.5.1. DELETE example
This example uses the interface list from Appendix C.3. This example This example uses the interface list from module ietf-interfaces
is deleting an instance of the interface list (SID = 1533): [RFC7223]. This example deletes an instance of the interface list
(SID = 1533):
REQ: DELETE /c/X9?k="eth0" REQ: DELETE /c/X9?k="eth0"
RES: 2.02 Deleted RES: 2.02 Deleted
4.4. Full datastore access 4.4. Full datastore access
The methods GET, PUT, POST, and DELETE can be used to request, The methods GET, PUT, POST, and DELETE can be used to request,
replace, create, and delete a whole datastore respectively. replace, create, and delete a whole datastore respectively.
skipping to change at page 24, line 34 skipping to change at page 23, line 39
DELETE /c DELETE /c
2.02 Deleted 2.02 Deleted
The content of the CBOR map represents the complete datastore of the The content of the CBOR map represents the complete datastore of the
server at the GET indication of after a successful processing of a server at the GET indication of after a successful processing of a
PUT or POST request. PUT or POST request.
4.4.1. Full datastore examples 4.4.1. Full datastore examples
The example uses the interface list and the clock container from The example uses the interface list from module ietf-interfaces
Appendix C.3. Assume that the datastore contains two modules ietf- [RFC7223] and the clock container from module ietf-system [RFC7317].
system (SID 1700) and ietf-interfaces (SID 1500); they contain the We assume that the datastore contains two modules ietf-system (SID
'interface' list (SID 1533) with one instance and the 'clock' 1700) and ietf-interfaces (SID 1500); they contain the 'interface'
container (SID 1721). After invocation of GET, a CBOR map with data list (SID 1533) with one instance and the 'clock' container (SID
nodes from these two modules is returned: 1721). After invocation of GET, a CBOR map with data nodes from
these two modules is returned:
REQ: GET /c REQ: GET /c
RES: 2.05 Content (Content-Format: application/yang-data+cbor) RES: 2.05 Content (Content-Format: application/yang-data+cbor)
{ {
1721 : { / Clock (SID 1721) / 1721 : { / Clock (SID 1721) /
+2: "2016-10-26T12:16:31Z", / current-datetime (SID 1723) / +2: "2016-10-26T12:16:31Z", / current-datetime (SID 1723) /
+1: "2014-10-05T09:00:00Z" / boot-datetime (SID 1722) / +1: "2014-10-05T09:00:00Z" / boot-datetime (SID 1722) /
}, },
1533 : [ 1533 : [
skipping to change at page 25, line 38 skipping to change at page 24, line 38
reported to a list of clients. The recommended path of the default reported to a list of clients. The recommended path of the default
event stream is /s. The server MAY support additional event stream event stream is /s. The server MAY support additional event stream
resources to address different notification needs. resources to address different notification needs.
Reception of notification instances is enabled with the CoAP Observe Reception of notification instances is enabled with the CoAP Observe
[RFC7641] function. Clients subscribe to the notifications by [RFC7641] function. Clients subscribe to the notifications by
sending a GET request with an "Observe" option, specifying the /s sending a GET request with an "Observe" option, specifying the /s
resource when the default stream is selected. resource when the default stream is selected.
Each response payload carries one or multiple notifications. The Each response payload carries one or multiple notifications. The
number of notification reported and the conditions used to remove number of notifications reported, and the conditions used to remove
notifications from the reported list is left to implementers. When notifications from the reported list is left to implementers. When
multiple notifications are reported, they MUST be ordered starting multiple notifications are reported, they MUST be ordered starting
from the newest notification at index zero. from the newest notification at index zero.
The format of notification contents is defined in The format of notification contents is defined in
[I-D.ietf-core-yang-cbor] section 4.2.1. For notification without [I-D.ietf-core-yang-cbor] section 4.2.1. For notification without
any content, a null value is returned. any content, a null value is returned.
An example implementation is: An example implementation is:
skipping to change at page 26, line 18 skipping to change at page 25, line 18
GET /<stream-resource> Observe(0) GET /<stream-resource> Observe(0)
2.05 Content (Content-Format :application/yang-instances+cbor) 2.05 Content (Content-Format :application/yang-instances+cbor)
CBOR array of CBOR map of instance-identifier, instance-value CBOR array of CBOR map of instance-identifier, instance-value
The array of data node instances may contain identical entries which The array of data node instances may contain identical entries which
have been generated at different times. have been generated at different times.
4.5.1. Notify Examples 4.5.1. Notify Examples
Suppose the server generates the event specified in Appendix C.4. By Let suppose the server generates the example-port-fault event as
executing a GET on the /s resource the client receives the following defined below.
response:
module example-port {
...
notification example-port-fault { // SID 60010
description
"Event generated if a hardware fault is detected";
leaf port-name { // SID 60011
type string;
}
leaf port-fault { // SID 60012
type string;
}
}
}
By executing a GET on the /s resource the client receives the
following response:
REQ: GET /s Observe(0) Token(0x93) REQ: GET /s Observe(0) Token(0x93)
RES: 2.05 Content (Content-Format :application/yang-tree+cbor) RES: 2.05 Content (Content-Format :application/yang-tree+cbor)
Observe(12) Token(0x93) Observe(12) Token(0x93)
[ [
{ {
60010 : { / example-port-fault (SID 60010) / 60010 : { / example-port-fault (SID 60010) /
+1 : "0/4/21", / port-name (SID 60011) / +1 : "0/4/21", / port-name (SID 60011) /
+2 : "Open pin 2" / port-fault (SID 60012) / +2 : "Open pin 2" / port-fault (SID 60012) /
skipping to change at page 27, line 5 skipping to change at page 26, line 33
In the example, the request returns a success response with the In the example, the request returns a success response with the
contents of the last two generated events. Consecutively the server contents of the last two generated events. Consecutively the server
will regularly notify the client when a new event is generated. will regularly notify the client when a new event is generated.
To check that the client is still alive, the server MUST send To check that the client is still alive, the server MUST send
Confirmable Message periodically. When the client does not confirm Confirmable Message periodically. When the client does not confirm
the notification from the server, the server will remove the client the notification from the server, the server will remove the client
from the list of observers [RFC7641]. from the list of observers [RFC7641].
4.5.2. The 'f' Uri-Query option
The 'f' (filter) option is used to indicate which subset of all
possible notifications is of interest. If not present, all events
notifications supported by the event stream are reported.
When not supported by a CoMI server, this option shall be ignored,
all events notifications are reported independently of the presence
and content of the 'f' (filter) option.
When present, this option contains a comma separated list of
notification SIDs. For example, the following request returns
notifications 60010 and 60020.
REQ: GET /s?f=60010,60020 Observe(0) Token(0x241)
4.6. RPC statements 4.6. RPC statements
The YANG "action" and "RPC" statements specify the execution of a The YANG "action" and "RPC" statements specify the execution of a
Remote procedure Call (RPC) in the server. It is invoked using a Remote procedure Call (RPC) in the server. It is invoked using a
POST method to an "Action" or "RPC" resource instance. POST method to an "Action" or "RPC" resource instance.
The request payload contains the values assigned to the input The request payload contains the values assigned to the input
container when specified. The response payload contains the values container when specified. The response payload contains the values
of the output container when specified. Both the input and output of the output container when specified. Both the input and output
containers are encoded in CBOR using the rules defined in containers are encoded in CBOR using the rules defined in
skipping to change at page 27, line 29 skipping to change at page 27, line 29
FORMAT: FORMAT:
POST /c/<instance identifier> POST /c/<instance identifier>
(Content-Format :application/yang-data+cbor) (Content-Format :application/yang-data+cbor)
CBOR map of SID, instance-value CBOR map of SID, instance-value
2.05 Content (Content-Format :application/yang-data+cbor) 2.05 Content (Content-Format :application/yang-data+cbor)
CBOR map of SID, instance-value CBOR map of SID, instance-value
4.6.1. RPC Example 4.6.1. RPC Example
The example is based on the YANG action specification of The example is based on the YANG action reset as defined in [RFC7950]
Appendix C.2. A server list is specified and the action "reset" (SID section 7.15.3 and annotated below with SIDs.
60002, base64: Opq), that is part of a "server instance" with key
value "myserver", is invoked. module example-server-farm {
yang-version 1.1;
namespace "urn:example:server-farm";
prefix "sfarm";
import ietf-yang-types {
prefix "yang";
}
list server { // SID 60000
key name;
leaf name { // SID 60001
type string;
}
action reset { // SID 60002
input {
leaf reset-at { // SID 60003
type yang:date-and-time;
mandatory true;
}
}
output {
leaf reset-finished-at { // SID 60004
type yang:date-and-time;
mandatory true;
}
}
}
}
}
This example invokes the 'reset' action (SID 60002, base64: Opq), of
the server instance with name equal to "myserver".
REQ: POST /c/Opq?k="myserver" REQ: POST /c/Opq?k="myserver"
(Content-Format :application/yang-data+cbor) (Content-Format :application/yang-data+cbor)
{ {
60002 : { 60002 : {
+1 : "2016-02-08T14:10:08Z09:00" / reset-at (SID 60003) / +1 : "2016-02-08T14:10:08Z09:00" / reset-at (SID 60003) /
} }
} }
RES: 2.05 Content (Content-Format :application/yang-data+cbor) RES: 2.05 Content (Content-Format :application/yang-data+cbor)
{ {
60002 : { 60002 : {
+2 : "2016-02-08T14:10:08Z09:18" / reset-finished-at (SID 60004)/ +2 : "2016-02-08T14:10:08Z09:18" / reset-finished-at (SID 60004)/
} }
} }
5. Access to MIB Data 5. Use of Block
Appendix C.5 shows a YANG module mapped from the SMI specification
"IP-MIB" [RFC4293]. The following example shows the
"ipNetToPhysicalEntry" list with 2 instances.
REQ: GET example.com/c/Oz1
RES: 2.05 Content (Content-Format: application/yang-data+cbor)
{
60021 : [ / ipNetToPhysicalEntry /
{
+1 : 1, / ipNetToPhysicalIfIndex (SID 60022) /
+2 : 1, / ipNetToPhysicalNetAddressType (SID 60023) /
+3 : h'0A000033', / ipNetToPhysicalNetAddress (SID 60024) /
+4 : h'00000A01172D',/ ipNetToPhysicalPhysAddress (SID 60025) /
+5 : 2333943, / ipNetToPhysicalLastUpdated (SID 60026) /
+6 : 4, / ipNetToPhysicalType (SID 60027) /
+7 : 1, / ipNetToPhysicalState (SID 60028) /
+8 : 1 / ipNetToPhysicalRowStatus (SID 60029) /
},
{
+1 : 1, / ipNetToPhysicalIfIndex (SID 60022) /
+2 : 1, / ipNetToPhysicalNetAddressType (SID 60023) /
+3 : h'09020304', / ipNetToPhysicalNetAddress (SID 60024) /
+4 : h'00000A36200A',/ ipNetToPhysicalPhysAddress (SID 60025) /
+5 : 2329836, / ipNetToPhysicalLastUpdated (SID 60026) /
+6 : 3, / ipNetToPhysicalType (SID 60027) /
+7 : 6, / ipNetToPhysicalState (SID 60028) /
+8 : 1 / ipNetToPhysicalRowStatus (SID 60029) /
}
]
}
6. Use of Block
The CoAP protocol provides reliability by acknowledging the UDP The CoAP protocol provides reliability by acknowledging the UDP
datagrams. However, when large pieces of data need to be datagrams. However, when large pieces of data need to be
transported, datagrams get fragmented, thus creating constraints on transported, datagrams get fragmented, thus creating constraints on
the resources in the client, server and intermediate routers. The the resources in the client, server and intermediate routers. The
block option [RFC7959] allows the transport of the total payload in block option [RFC7959] allows the transport of the total payload in
individual blocks of which the size can be adapted to the underlying individual blocks of which the size can be adapted to the underlying
transport sizes such as: (UDP datagram size ~64KiB, IPv6 MTU of 1280, 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 IEEE 802.15.4 payload of 60-80 bytes). Each block is individually
acknowledged to guarantee reliability. acknowledged to guarantee reliability.
skipping to change at page 29, line 18 skipping to change at page 29, line 33
should be taken that the whole data representation is sent in should be taken that the whole data representation is sent in
multiple blocks sequentially without interruption. On the server, multiple blocks sequentially without interruption. On the server,
values are changed, lists are re-ordered, extended or reduced. When values are changed, lists are re-ordered, extended or reduced. When
these actions happen during the serialization of the contents of the these actions happen during the serialization of the contents of the
resource, the transported results do not correspond with a state resource, the transported results do not correspond with a state
having occurred in the server; or worse the returned values are having occurred in the server; or worse the returned values are
inconsistent. For example: array length does not correspond with the inconsistent. For example: array length does not correspond with the
actual number of items. It may be advisable to use Indefinite-length actual number of items. It may be advisable to use Indefinite-length
CBOR arrays and maps, which are foreseen for data streaming purposes. CBOR arrays and maps, which are foreseen for data streaming purposes.
7. Application Discovery 6. Application Discovery
Two application discovery mechanisms are supported by CoMI, the YANG Two application discovery mechanisms are supported by CoMI, the YANG
library data model as defined by [I-D.veillette-core-yang-library] library data model as defined by [I-D.veillette-core-yang-library]
and the CORE resource discovery [RFC6690]. Implementers may choose and the CORE resource discovery [RFC6690]. Implementers may choose
to implement one or the other or both. to implement one or the other or both.
7.1. YANG library 6.1. YANG library
The YANG library data model [I-D.veillette-core-yang-library] The YANG library data model [I-D.veillette-core-yang-library]
provides a high level description of the resources available. The provides a high level description of the resources available. The
YANG library contains the list of modules, features and deviations YANG library contains the list of modules, features and deviations
supported by the CoMI server. From this information, CoMI clients supported by the CoMI server. From this information, CoMI clients
can infer the list of data nodes supported and the interaction model can infer the list of data nodes supported and the interaction model
to be used to access them. This module also contains the list of to be used to access them. This module also contains the list of
datastores implemented. datastores implemented.
The location of the YANG library can be found by sending a GET The location of the YANG library can be found by sending a GET
request to "/.well-known/core" including a resource type (RT) request to "/.well-known/core" including a resource type (RT)
parameter with the value "core.c.yl". Upon success, the return parameter with the value "core.c.yl". Upon success, the return
payload will contain the root resource of the YANG library module. payload will contain the root resource of the YANG library module.
REQ: GET /.well-known/core?rt=core.c.yl REQ: GET /.well-known/core?rt=core.c.yl
RES: 2.05 Content (Content-Format: application/link-format) RES: 2.05 Content (Content-Format: application/link-format)
</c/kv >;rt="core.c.yl" </c/kv >;rt="core.c.yl"
7.2. Resource Discovery 6.2. Resource Discovery
Even if the YANG library provides all the information needed for Even if the YANG library provides all the information needed for
application discovery, the implementation of Resource discovery as application discovery, the implementation of Resource discovery as
defined by [RFC6690] can be desirable for a seamless integration with defined by [RFC6690] can be desirable for a seamless integration with
other CoAP interfaces and services. other CoAP interfaces and services.
7.2.1. Datastore Resource Discovery 6.2.1. Datastore Resource Discovery
The presence and location of (path to) each datastore implemented by The presence and location of (path to) each datastore implemented by
the CoMI server can be discovered by sending a GET request to the CoMI server can be discovered by sending a GET request to
"/.well-known/core" including a resource type (RT) parameter with the "/.well-known/core" including a resource type (RT) parameter with the
value "core.c.ds". value "core.c.ds".
Upon success, the return payload contains the list of datastore Upon success, the return payload contains the list of datastore
resources. resources.
Each datastore returned is further qualified using the "ds" Link- Each datastore returned is further qualified using the "ds" Link-
skipping to change at page 30, line 32 skipping to change at page 30, line 46
; SID assigned to the datastore identity ; SID assigned to the datastore identity
sid = 1*DIGIT sid = 1*DIGIT
For example: For example:
REQ: GET /.well-known/core?rt=core.c.ds REQ: GET /.well-known/core?rt=core.c.ds
RES: 2.05 Content (Content-Format: application/link-format) RES: 2.05 Content (Content-Format: application/link-format)
</c>; rt="core.c.ds";ds= 1029 </c>; rt="core.c.ds";ds= 1029
7.2.2. Data node Resource Discovery 6.2.2. Data node Resource Discovery
The presence and location of (path to) each data node implemented by The presence and location of (path to) each data node implemented by
the CoMI server are discovered by sending a GET request to "/.well- the CoMI server are discovered by sending a GET request to "/.well-
known/core" including a resource type (RT) parameter with the value known/core" including a resource type (RT) parameter with the value
"core.c.dn". "core.c.dn".
Upon success, the return payload contains the SID assigned to each Upon success, the return payload contains the SID assigned to each
data node and their location. data node and their location.
The example below shows the discovery of the presence and location of The example below shows the discovery of the presence and location of
skipping to change at page 31, line 4 skipping to change at page 31, line 18
The example below shows the discovery of the presence and location of The example below shows the discovery of the presence and location of
data nodes. Data nodes '/ietf-system:system-state/clock/boot- data nodes. Data nodes '/ietf-system:system-state/clock/boot-
datetime' (SID 1722) and '/ietf-system:system-state/clock/current- datetime' (SID 1722) and '/ietf-system:system-state/clock/current-
datetime' (SID 1723) are returned. datetime' (SID 1723) are returned.
REQ: GET /.well-known/core?rt=core.c.dn REQ: GET /.well-known/core?rt=core.c.dn
RES: 2.05 Content (Content-Format: application/link-format) RES: 2.05 Content (Content-Format: application/link-format)
</c/a6>;rt="core.c.dn", </c/a6>;rt="core.c.dn",
</c/a7>;rt="core.c.dn" </c/a7>;rt="core.c.dn"
The list of data nodes may become prohibitively long. The list of data nodes may become prohibitively long.
Implementations MAY return a subset of this list or can rely solely Implementations MAY return a subset of this list or can rely solely
on the YANG library. on the YANG library.
7.2.3. Event stream Resource Discovery 6.2.3. Event stream Resource Discovery
The presence and location of (path to) each event stream implemented The presence and location of (path to) each event stream implemented
by the CoMI server are discovered by sending a GET request to by the CoMI server are discovered by sending a GET request to
"/.well-known/core" including a resource type (RT) parameter with the "/.well-known/core" including a resource type (RT) parameter with the
value "core.c.es". value "core.c.es".
Upon success, the return payload contains the list of event stream Upon success, the return payload contains the list of event stream
resources. resources.
For example: For example:
REQ: GET /.well-known/core?rt=core.c.es REQ: GET /.well-known/core?rt=core.c.es
RES: 2.05 Content (Content-Format: application/link-format) RES: 2.05 Content (Content-Format: application/link-format)
</s>;rt="core.c.es" </s>;rt="core.c.es"
8. Error Handling 7. Error Handling
In case a request is received which cannot be processed properly, the In case a request is received which cannot be processed properly, the
CoMI server MUST return an error message. This error message MUST CoMI server MUST return an error message. This error message MUST
contain a CoAP 4.xx or 5.xx response code. contain a CoAP 4.xx or 5.xx response code.
Errors returned by a CoMI server can be broken into two categories, Errors returned by a CoMI server can be broken into two categories,
those associated to the CoAP protocol itself and those generated those associated to the CoAP protocol itself and those generated
during the validation of the YANG data model constrains as described during the validation of the YANG data model constrains as described
in [RFC7950] section 8. in [RFC7950] section 8.
skipping to change at page 33, line 47 skipping to change at page 34, line 16
server when the validation of the 'pattern' property fails. server when the validation of the 'pattern' property fails.
o error-tag 'missing-element' is returned by the CoMI server when o error-tag 'missing-element' is returned by the CoMI server when
the operation requested by a CoMI client fail to comply with the the operation requested by a CoMI client fail to comply with the
'mandatory' constraint defined. The 'mandatory' constraint is 'mandatory' constraint defined. The 'mandatory' constraint is
enforced for leafs and choices, unless the node or any of its enforced for leafs and choices, unless the node or any of its
ancestors have a 'when' condition or 'if-feature' expression that ancestors have a 'when' condition or 'if-feature' expression that
evaluates to 'false'. evaluates to 'false'.
* error-app-tag 'missing-key' is returned by the CoMI server to * error-app-tag 'missing-key' is returned by the CoMI server to
further qualify an missing-element error. This error is further qualify a missing-element error. This error is
returned when the CoMI client tries to create or list instance, returned when the CoMI client tries to create or list instance,
without all the 'key' specified or when the CoMI client tries without all the 'key' specified or when the CoMI client tries
to delete a leaf listed as a 'key'. to delete a leaf listed as a 'key'.
* error-app-tag 'missing-input-parameter' is returned by the CoMI * error-app-tag 'missing-input-parameter' is returned by the CoMI
server when the input parameters of an RPC or action are server when the input parameters of an RPC or action are
incomplete. incomplete.
o error-tag 'unknown-element' is returned by the CoMI server when o 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 the CoMI client tries to access a data node of a YANG module not
skipping to change at page 34, line 48 skipping to change at page 35, line 18
+4 : 1011, / error-tag (SID 1028) / +4 : 1011, / error-tag (SID 1028) /
/ = invalid-value (SID 1011) / / = invalid-value (SID 1011) /
+1 : 1018, / error-app-tag (SID 1025) / +1 : 1018, / error-app-tag (SID 1025) /
/ = not-in-range (SID 1018) / / = not-in-range (SID 1018) /
+2 : 1740, / error-data-node (SID 1026) / +2 : 1740, / error-data-node (SID 1026) /
/ = timezone-utc-offset (SID 1740) / / = timezone-utc-offset (SID 1740) /
+3 : "maximum value exceeded" / error-message (SID 1027) / +3 : "maximum value exceeded" / error-message (SID 1027) /
} }
} }
9. Security Considerations 8. Security Considerations
For secure network management, it is important to restrict access to For secure network management, it is important to restrict access to
configuration variables only to authorized parties. CoMI re-uses the configuration variables only to authorized parties. CoMI re-uses the
security mechanisms already available to CoAP, this includes DTLS security mechanisms already available to CoAP, this includes DTLS
[RFC6347] for protected access to resources, as well suitable [RFC6347] for protected access to resources, as well suitable
authentication and authorization mechanisms. authentication and authorization mechanisms.
Among the security decisions that need to be made are selecting Among the security decisions that need to be made are selecting
security modes and encryption mechanisms (see [RFC7252]). This security modes and encryption mechanisms (see [RFC7252]). This
requires a trade-off, as the NoKey mode gives no protection at all, 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 but is easy to implement, whereas the X.509 mode is quite secure, but
may be too complex for constrained devices. may be too complex for constrained devices.
In addition, mechanisms for authentication and authorization may need In addition, mechanisms for authentication and authorization may need
to be selected. to be selected.
CoMI avoids defining new security mechanisms as much as possible. CoMI avoids defining new security mechanisms as much as possible.
However, some adaptations may still be required, to cater for CoMI's However, some adaptations may still be required, to cater for CoMI's
specific requirements. specific requirements.
10. IANA Considerations 9. IANA Considerations
10.1. Resource Type (rt=) Link Target Attribute Values Registry 9.1. Resource Type (rt=) Link Target Attribute Values Registry
This document adds the following resource type to the "Resource Type This document adds the following resource type to the "Resource Type
(rt=) Link Target Attribute Values", within the "Constrained RESTful (rt=) Link Target Attribute Values", within the "Constrained RESTful
Environments (CoRE) Parameters" registry. Environments (CoRE) Parameters" registry.
+-----------+---------------------+-----------+ +-----------+---------------------+-----------+
| Value | Description | Reference | | Value | Description | Reference |
+-----------+---------------------+-----------+ +-----------+---------------------+-----------+
| core.c.ds | YANG datastore | RFC XXXX | | core.c.ds | YANG datastore | RFC XXXX |
| | | | | | | |
| core.c.dn | YANG data node | RFC XXXX | | core.c.dn | YANG data node | RFC XXXX |
| | | | | | | |
| core.c.yl | YANG module library | RFC XXXX | | core.c.yl | YANG module library | RFC XXXX |
| | | | | | | |
| core.c.es | YANG event stream | RFC XXXX | | core.c.es | YANG event stream | RFC XXXX |
+-----------+---------------------+-----------+ +-----------+---------------------+-----------+
// RFC Ed.: replace RFC XXXX with this RFC number and remove this // RFC Ed.: replace RFC XXXX with this RFC number and remove this
note. note.
10.2. CoAP Content-Formats Registry 9.2. CoAP Content-Formats Registry
This document adds the following Content-Format to the "CoAP Content- This document adds the following Content-Format to the "CoAP Content-
Formats", within the "Constrained RESTful Environments (CoRE) Formats", within the "Constrained RESTful Environments (CoRE)
Parameters" registry. Parameters" registry.
+-----------------------------------+-------------+-----------+ +-----------------------------------+-------------+-----------+
| Media Type | Encoding ID | Reference | | Media Type | Encoding ID | Reference |
+-----------------------------------+-------------+-----------+ +-----------------------------------+-------------+-----------+
| application/yang-data+cbor | XXX | RFC XXXX | | application/yang-data+cbor | XXX | RFC XXXX |
| | | | | | | |
| application/yang-identifiers+cbor | XXX | RFC XXXX | | application/yang-identifiers+cbor | XXX | RFC XXXX |
| | | | | | | |
| application/yang-instances+cbor | XXX | RFC XXXX | | application/yang-instances+cbor | XXX | RFC XXXX |
+-----------------------------------+-------------+-----------+ +-----------------------------------+-------------+-----------+
// RFC Ed.: replace XXX with assigned IDs and remove this note. // // RFC Ed.: replace XXX with assigned IDs and remove this note. //
RFC Ed.: replace RFC XXXX with this RFC number and remove this note. RFC Ed.: replace RFC XXXX with this RFC number and remove this note.
10.3. Media Types Registry 9.3. Media Types Registry
This document adds the following media types to the "Media Types" This document adds the following media types to the "Media Types"
registry. registry.
+-----------------------+----------------------------+-----------+ +-----------------------+----------------------------+-----------+
| Name | Template | Reference | | Name | Template | Reference |
+-----------------------+----------------------------+-----------+ +-----------------------+----------------------------+-----------+
| yang-data+cbor | application/yang-data+cbor | RFC XXXX | | yang-data+cbor | application/yang-data+cbor | RFC XXXX |
| | | | | | | |
| yang-identifiers+cbor | application/ | RFC XXXX | | yang-identifiers+cbor | application/ | RFC XXXX |
skipping to change at page 37, line 34 skipping to change at page 38, line 18
o Author: Michel Veillette, ietf&augustcellars.com o Author: Michel Veillette, ietf&augustcellars.com
o Change Controller: IESG o Change Controller: IESG
o Provisional registration? No o Provisional registration? No
// RFC Ed.: replace RFC XXXX with this RFC number and remove this // RFC Ed.: replace RFC XXXX with this RFC number and remove this
note. note.
11. Acknowledgements 10. Acknowledgements
We are very grateful to Bert Greevenbosch who was one of the original We are very grateful to Bert Greevenbosch who was one of the original
authors of the CoMI specification and specified CBOR encoding and use authors of the CoMI specification.
of hashes.
Mehmet Ersue and Bert Wijnen explained the encoding aspects of PDUs Mehmet Ersue and Bert Wijnen explained the encoding aspects of PDUs
transported under SNMP. Carsten Bormann has given feedback on the transported under SNMP. Carsten Bormann has given feedback on the
use of CBOR. use of CBOR.
The draft has benefited from comments (alphabetical order) by Rodney The draft has benefited from comments (alphabetical order) by Rodney
Cummings, Dee Denteneer, Esko Dijk, Michael van Hartskamp, Tanguy Cummings, Dee Denteneer, Esko Dijk, Michael van Hartskamp, Tanguy
Ropitault, Juergen Schoenwaelder, Anuj Sehgal, Zach Shelby, Hannes Ropitault, Juergen Schoenwaelder, Anuj Sehgal, Zach Shelby, Hannes
Tschofenig, Michael Verschoor, and Thomas Watteyne. Tschofenig, Michael Verschoor, and Thomas Watteyne.
12. References 11. References
12.1. Normative References 11.1. Normative References
[I-D.ietf-core-sid] [I-D.ietf-core-sid]
Veillette, M. and A. Pelov, "YANG Schema Item iDentifier Veillette, M., Pelov, A., and I. Petrov, "YANG Schema Item
(SID)", draft-ietf-core-sid-04 (work in progress), June iDentifier (SID)", draft-ietf-core-sid-06 (work in
2018. progress), March 2019.
[I-D.ietf-core-yang-cbor] [I-D.ietf-core-yang-cbor]
Veillette, M., Pelov, A., Turner, R., and A. Minaburo, Veillette, M., Petrov, I., and A. Pelov, "CBOR Encoding of
"CBOR Encoding of Data Modeled with YANG", draft-ietf- Data Modeled with YANG", draft-ietf-core-yang-cbor-10
core-yang-cbor-07 (work in progress), September 2018. (work in progress), April 2019.
[I-D.veillette-core-yang-library] [I-D.veillette-core-yang-library]
Veillette, M., "Constrained YANG Module Library", draft- Veillette, M. and I. Petrov, "Constrained YANG Module
veillette-core-yang-library-03 (work in progress), Library", draft-veillette-core-yang-library-04 (work in
September 2018. progress), March 2019.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
<https://www.rfc-editor.org/info/rfc4648>. <https://www.rfc-editor.org/info/rfc4648>.
skipping to change at page 39, line 33 skipping to change at page 40, line 10
[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
<https://www.rfc-editor.org/info/rfc8040>. <https://www.rfc-editor.org/info/rfc8040>.
[RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and
FETCH Methods for the Constrained Application Protocol FETCH Methods for the Constrained Application Protocol
(CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017,
<https://www.rfc-editor.org/info/rfc8132>. <https://www.rfc-editor.org/info/rfc8132>.
12.2. Informative References 11.2. Informative References
[RFC4293] Routhier, S., Ed., "Management Information Base for the
Internet Protocol (IP)", RFC 4293, DOI 10.17487/RFC4293,
April 2006, <https://www.rfc-editor.org/info/rfc4293>.
[RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer
Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347,
January 2012, <https://www.rfc-editor.org/info/rfc6347>. January 2012, <https://www.rfc-editor.org/info/rfc6347>.
[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, Format", RFC 6690, DOI 10.17487/RFC6690, August 2012,
<https://www.rfc-editor.org/info/rfc6690>. <https://www.rfc-editor.org/info/rfc6690>.
[RFC7223] Bjorklund, M., "A YANG Data Model for Interface [RFC7223] Bjorklund, M., "A YANG Data Model for Interface
skipping to change at page 40, line 16 skipping to change at page 40, line 35
System Management", RFC 7317, DOI 10.17487/RFC7317, August System Management", RFC 7317, DOI 10.17487/RFC7317, August
2014, <https://www.rfc-editor.org/info/rfc7317>. 2014, <https://www.rfc-editor.org/info/rfc7317>.
[RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
and R. Wilton, "Network Management Datastore Architecture and R. Wilton, "Network Management Datastore Architecture
(NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,
<https://www.rfc-editor.org/info/rfc8342>. <https://www.rfc-editor.org/info/rfc8342>.
Appendix A. ietf-comi YANG module Appendix A. ietf-comi YANG module
<CODE BEGINS> file "ietf-comi@2018-09-26.yang" <CODE BEGINS> file "ietf-comi@2019-03-28.yang"
module ietf-comi { module ietf-comi {
yang-version 1.1; yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-comi"; namespace "urn:ietf:params:xml:ns:yang:ietf-comi";
prefix comi; prefix comi;
import ietf-datastores { import ietf-datastores {
prefix ds; prefix ds;
} }
import ietf-restconf { import ietf-restconf {
prefix rc; prefix rc;
description description
"This import statement is only present to access "This import statement is required to access
the yang-data extension defined in RFC 8040."; the yang-data extension defined in RFC 8040.";
reference "RFC 8040: RESTCONF Protocol"; reference "RFC 8040: RESTCONF Protocol";
} }
organization organization
"IETF Core Working Group"; "IETF Core Working Group";
contact contact
"Michel Veillette "Michel Veillette
<mailto:michel.veillette@trilliantinc.com> <mailto:michel.veillette@trilliantinc.com>
Alexander Pelov Alexander Pelov
<mailto:alexander@ackl.io> <mailto:alexander@ackl.io>
Peter van der Stok Peter van der Stok
<mailto:consultancy@vanderstok.org> <mailto:consultancy@vanderstok.org>
Andy Bierman Andy Bierman
<mailto:andy@yumaworks.com>"; <mailto:andy@yumaworks.com>";
description description
"This module contains the different definitions required "This module contains the different definitions required
by the CoMI protocol."; by the CoMI protocol.";
revision 2018-09-26 { revision 2019-03-28 {
description
"Use of YANG data template for the error payload.
Definition of the unified datastore.";
reference
"[I-D.ietf-core-comi] CoAP Management Interface";
}
revision 2017-07-01 {
description description
"Initial revision."; "Initial revision.";
reference reference
"[I-D.ietf-core-comi] CoAP Management Interface"; "[I-D.ietf-core-comi] CoAP Management Interface";
} }
typedef sid {
type uint64;
description
"YANG Schema Item iDentifier";
reference
"[I-D.ietf-core-sid] YANG Schema Item iDentifier (SID)";
}
identity unified { identity unified {
base ds:datastore; base ds:datastore;
description description
"The unified configuration and operational state datastore."; "Identifier of the unified configuration and operational
state datastore.";
} }
identity error-tag { identity error-tag {
description description
"Base identity for error-tag."; "Base identity for error-tag.";
} }
identity operation-failed { identity operation-failed {
base error-tag; base error-tag;
description description
skipping to change at page 45, line 47 skipping to change at page 46, line 4
description description
"The application-specific error-tag."; "The application-specific error-tag.";
} }
leaf error-data-node { leaf error-data-node {
type instance-identifier; type instance-identifier;
description description
"When the error reported is caused by a specific data node, "When the error reported is caused by a specific data node,
this leaf identifies the data node in error."; this leaf identifies the data node in error.";
} }
leaf error-message { leaf error-message {
type string; type string;
description description
"A message describing the error."; "A message describing the error.";
} }
} }
} }
} }
<CODE ENDS> <CODE ENDS>
Appendix B. ietf-comi .sid file Appendix B. ietf-comi .sid file
{ {
"assignment-ranges": [ "assignment-ranges": [
{ {
"entry-point": 1000, "entry-point": 1000,
"size": 100 "size": 100
} }
], ],
"module-name": "ietf-comi", "module-name": "ietf-comi",
"module-revision": "2018-09-26", "module-revision": "2019-03-28",
"items": [ "items": [
{ {
"namespace": "module", "namespace": "module",
"identifier": "ietf-comi", "identifier": "ietf-comi",
"sid": 1000 "sid": 1000
}, },
{ {
"namespace": "identity", "namespace": "identity",
"identifier": "bad-element", "identifier": "bad-element",
"sid": 1001 "sid": 1001
skipping to change at page 49, line 31 skipping to change at page 49, line 35
"sid": 1027 "sid": 1027
}, },
{ {
"namespace": "data", "namespace": "data",
"identifier": "/ietf-comi:error/error-tag", "identifier": "/ietf-comi:error/error-tag",
"sid": 1028 "sid": 1028
} }
] ]
} }
Appendix C. YANG example specifications
This appendix shows five YANG example specifications taken over from
as many existing YANG modules. Each YANG item identifier is
accompanied by its SID shown after the "//" comment sign.
C.1. ietf-system
Excerpt of the YANG module ietf-system [RFC7317].
module ietf-system { // SID 1700
container system { // SID 1717
container clock { // SID 1738
choice timezone {
case timezone-name {
leaf timezone-name { // SID 1739
type timezone-name;
}
}
case timezone-utc-offset {
leaf timezone-utc-offset { // SID 1740
type int16 {
}
}
}
}
}
container ntp { // SID 1754
leaf enabled { // SID 1755
type boolean;
default true;
}
list server { // SID 1756
key name;
leaf name { // SID 1759
type string;
}
choice transport {
case udp {
container udp { // SID 1761
leaf address { // SID 1762
type inet:host;
}
leaf port { // SID 1763
type inet:port-number;
}
}
}
}
leaf association-type { // SID 1757
type enumeration {
enum server {
}
enum peer {
}
enum pool {
}
}
}
leaf iburst { // SID 1758
type boolean;
}
leaf prefer { // SID 1760
type boolean;
default false;
}
}
}
container system-state { // SID 1720
container clock { // SID 1721
leaf current-datetime { // SID 1723
type yang:date-and-time;
}
leaf boot-datetime { // SID 1722
type yang:date-and-time;
}
}
}
}
C.2. server list
Taken over from [RFC7950] section 7.15.3.
module example-server-farm {
yang-version 1.1;
namespace "urn:example:server-farm";
prefix "sfarm";
import ietf-yang-types {
prefix "yang";
}
list server { // SID 60000
key name;
leaf name { // SID 60001
type string;
}
action reset { // SID 60002
input {
leaf reset-at { // SID 60003
type yang:date-and-time;
mandatory true;
}
}
output {
leaf reset-finished-at { // SID 60004
type yang:date-and-time;
mandatory true;
}
}
}
}
}
C.3. interfaces
Excerpt of the YANG module ietf-interfaces [RFC7223].
module ietf-interfaces { // SID 1500
container interfaces { // SID 1505
list interface { // SID 1533
key "name";
leaf name { // SID 1537
type string;
}
leaf description { // SID 1534
type string;
}
leaf type { // SID 1538
type identityref {
base interface-type;
}
mandatory true;
}
leaf enabled { // SID 1535
type boolean;
default "true";
}
leaf link-up-down-trap-enable { // SID 1536
if-feature if-mib;
type enumeration {
enum enabled {
value 1;
}
enum disabled {
value 2;
}
}
}
}
}
}
C.4. Example-port
Notification example defined within this document.
module example-port {
...
notification example-port-fault { // SID 60010
description
"Event generated if a hardware fault on a
line card port is detected";
leaf port-name { // SID 60011
type string;
description "Port name";
}
leaf port-fault { // SID 60012
type string;
description "Error condition detected";
}
}
}
C.5. IP-MIB
The YANG translation of the SMI specifying the IP-MIB [RFC4293],
extended with example SID numbers, yields:
module IP-MIB {
import IF-MIB {
prefix if-mib;
}
import INET-ADDRESS-MIB {
prefix inet-address;
}
import SNMPv2-TC {
prefix smiv2;
}
import ietf-inet-types {
prefix inet;
}
import yang-smi {
prefix smi;
}
import ietf-yang-types {
prefix yang;
}
container ip { // SID 60020
list ipNetToPhysicalEntry { // SID 60021
key "ipNetToPhysicalIfIndex
ipNetToPhysicalNetAddressType
ipNetToPhysicalNetAddress";
leaf ipNetToPhysicalIfIndex { // SID 60022
type if-mib:InterfaceIndex;
}
leaf ipNetToPhysicalNetAddressType { // SID 60023
type inet-address:InetAddressType;
}
leaf ipNetToPhysicalNetAddress { // SID 60024
type inet-address:InetAddress;
}
leaf ipNetToPhysicalPhysAddress { // SID 60025
type yang:phys-address {
length "0..65535";
}
}
leaf ipNetToPhysicalLastUpdated { // SID 60026
type yang:timestamp;
}
leaf ipNetToPhysicalType { // SID 60027
type enumeration {
enum "other" {
value 1;
}
enum "invalid" {
value 2;
}
enum "dynamic" {
value 3;
}
enum "static" {
value 4;
}
enum "local" {
value 5;
}
}
}
leaf ipNetToPhysicalState { // SID 60028
type enumeration {
enum "reachable" {
value 1;
}
enum "stale" {
value 2;
}
enum "delay" {
value 3;
}
enum "probe" {
value 4;
}
enum "invalid" {
value 5;
}
enum "unknown" {
value 6;
}
enum "incomplete" {
value 7;
}
}
}
leaf ipNetToPhysicalRowStatus { // SID 60029
type smiv2:RowStatus;
} // list ipNetToPhysicalEntry
} // container ip
} // module IP-MIB
Authors' Addresses Authors' Addresses
Michel Veillette (editor) Michel Veillette (editor)
Trilliant Networks Inc. Trilliant Networks Inc.
610 Rue du Luxembourg 610 Rue du Luxembourg
Granby, Quebec J2J 2V2 Granby, Quebec J2J 2V2
Canada Canada
Email: michel.veillette@trilliant.com Email: michel.veillette@trilliant.com
 End of changes. 73 change blocks. 
479 lines changed or deleted 197 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/