One document matched: draft-ietf-lmap-restconf-01.xml
<?xml version="1.0" encoding="US-ASCII" ?>
<!DOCTYPE rfc SYSTEM "http://xml.resource.org/authoring/rfc2629.dtd" [
<!ENTITY rfc2119 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
<!ENTITY rfc3688 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3688.xml'>
<!ENTITY rfc6991 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.6991.xml'>
<!ENTITY rfc6020 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.6020.xml'>
<!ENTITY rfc7223 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.7223.xml'>
<!ENTITY rfc7230 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.7230.xml'>
<!ENTITY rfc7277 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.7277.xml'>
<!ENTITY rfc7317 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.7317.xml'>
<!ENTITY rfc7594 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.7594.xml'>
<!ENTITY I-D.ietf-lmap-information-model SYSTEM "http://xml2rfc.ietf.org/public/rfc/bibxml-ids/reference.I-D.ietf-lmap-information-model.xml">
<!ENTITY I-D.ietf-netconf-restconf SYSTEM "http://xml2rfc.ietf.org/public/rfc/bibxml-ids/reference.I-D.ietf-netconf-restconf">
<!ENTITY I-D.ietf-netconf-call-home SYSTEM "http://xml2rfc.ietf.org/public/rfc/bibxml-ids/reference.I-D.ietf-netconf-call-home">
<!ENTITY I-D.ietf-netconf-server-model SYSTEM "http://xml2rfc.ietf.org/public/rfc/bibxml-ids/reference.I-D.ietf-netconf-server-model">
<!ENTITY I-D.ietf-lmap-yang SYSTEM "http://xml2rfc.ietf.org/public/rfc/bibxml-ids/reference.I-D.ietf-lmap-yang">
<!-- <!ENTITY I-D.starkcarey-lmap-protocol-criteria SYSTEM "http://xml2rfc.ietf.org/public/rfc/bibxml-ids/reference.I-D.starkcarey-lmap-protocol-criteria"> -->
]>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="3"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="std" docName="draft-ietf-lmap-restconf-01.txt" ipr="trust200902">
<front>
<title abbrev="LMAP Data Model">
Using RESTCONF with LMAP Measurement Agents
</title>
<author fullname="Juergen Schoenwaelder" initials="J."
surname="Schoenwaelder">
<organization>Jacobs University Bremen</organization>
<address>
<email>j.schoenwaelder@jacobs-university.de</email>
</address>
</author>
<author fullname="Vaibhav Bajpai" initials="V."
surname="Bajpai">
<organization>Jacobs University Bremen</organization>
<address>
<email>v.bajpai@jacobs-university.de</email>
</address>
</author>
<date year="2015" />
<area>Operations and Management</area>
<keyword>LMAP</keyword>
<keyword>YANG</keyword>
<keyword>RESTCONF</keyword>
<abstract>
<t>
This document describes how RESTCONF can be used with a YANG
data model for Large-Scale Measurement Platforms (LMAP).
</t>
</abstract>
</front>
<middle>
<section title="Introduction">
<t>
This document discusses how a Controller can use the RESTCONF
protocol <xref target="I-D.ietf-netconf-restconf"/> to
configure Large-Scale Measurement of Broadband Performance
(LMAP) Measurement Agents <xref target="RFC7594"/>. It also
discusses how RESTCONF can be used by a Measurement Agent to
report measurement results to a Collector.
</t>
<t>
Measurement Agents may be deployed as separate hardware
devices or as functions embedded in consumer electronic
devices and home routers or as pure software solutions that
can be installed on off-the-shelf computing equipment.
Measurement Agents receive instructions from a Controller
about when and how to conduct what measurements (the
measurement schedule) and how and when to report measurement
results to a data Collector (the report schedule). Further
information about the interaction between Measurement Agents
and Controllers and Collectors can be found in <xref
target="RFC7594"/>.
</t>
<t>
The LMAP information model <xref
target="I-D.ietf-lmap-information-model"/> defines the
information exchanged between a Controller and an Measurement
Agent and the information exchanged between an Measurement
Agent and a Collector. An information model is conceptual and
protocol-independent. A concrete YANG <xref target="RFC6020"/>
data model derived from the conceptual information model is
defined in <xref target="I-D.ietf-lmap-yang"/>.
</t>
<section title="Terminology">
<t>
This document uses the LMAP terminology defined in <xref
target="RFC7594"/>.
</t>
<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"></xref>.
</t>
</section>
</section>
<section title="Overview of RESTCONF">
<t>
The RESTCONF protocol <xref
target="I-D.ietf-netconf-restconf"/> provides a REST-like
interface to access and manipulate a so-called unified YANG
datastore <xref target="RFC6020"/>. The basic idea behind
RESTCONF is expose a YANG datastores as a collection of Web
resources that can be manipulated using standard HTTP <xref
target="RFC7230"/> DELETE, PATCH, POST, and PUT methods. The
resource hierarchy is derived from the nesting structure of
the YANG schema tree, leading to a so-called data model driven
REST API.
</t>
<t>
RESTCONF is essentially a convention how to use HTTP over TLS
to access a datastore that has a structure defined by a YANG
data model. The data is exchanged in XML encoding or JSON
encoding.
</t>
<t>
The normal mode of operation is that the RESTCONF client
initiates a secure transport to the RESTCONF server. For
devices located behind a NAT, a so called 'call-home'
mechanism has been defined <xref
target="I-D.ietf-netconf-call-home"/> that enables the
RESTCONF server to establish a secure transport to a RESTCONF
client. Note that call home only changes the TCP connection
establishment, the TLS and HTTP client/server roles do not
change. The policy used to call home can be configured
through a configuration data model <xref
target="I-D.ietf-netconf-server-model"/>. This model provides
a mechanism to configure a list of redundant endpoints and it
provides control over call-home policies (e.g, call-home
frequency, idle-timers, keep-alive timers).
</t>
</section>
<section title="RESTCONF as LMAP Control Protocol">
<t>
It is straight-forward to use RESTCONF as a control
protocol. The YANG data model <xref
target="I-D.ietf-lmap-yang"/> derived from the underlying
information model <xref
target="I-D.ietf-lmap-information-model"/> translates into a
collection of RESTCONF resources that can be manipulated at
various levels of granularity using DELETE, PATCH, POST, and
PUT methods.
</t>
<t>
An example exchange showing a REST call to create a schedule
object is shown in <xref target="ex-control"/>.
</t>
</section>
<section title="RESTCONF as LMAP Report Protocol">
<t>
For reporting results from the Measurement Agent to a
Collector, the Collector is assumed to act as a RESTCONF
server. The Measurement Agent pushes results to the Collector
by invoking an operation on the Controller.
</t>
</section>
<!--
<section title="Conclusion">
<t>
This document discusses how RESTCONF can be used as a control
protocol and a report protocol for Large-Scale Measurement
Platforms (LMAP). The benefit of using RESTCONF is that no new
protocol work needs to be done. Additional benefits derive
from using YANG and a data model driven approach. Despite the
reuse of existing tools, using a data model driven approach
allows to easily reuse other data models (e.g., network
interfaces <xref target="RFC7223"/>, <xref target="RFC7277"/>
or general system services <xref target="RFC7317"/>) in order
to export additional status information about an MA to a
Controller.
</t>
</section>
-->
<section title="Security Considerations">
<t>
TBD
</t>
</section>
<section title="IANA Considerations">
<t>
This document has no requests for IANA.
</t>
</section>
<section title="Acknowledgements">
<t>
Juergen Schoenwaelder and Vaibhav Bajpai worked in part on the
Leone research project, which received funding from the
European Union Seventh Framework Programme [FP7/2007-2013]
under grant agreement number 317647.
</t>
<t>
Juergen Schoenwaelder and Vaibhav Bajpai were partly funded by
Flamingo, a Network of Excellence project (ICT-318488)
supported by the European Commission under its Seventh
Framework Programme.
</t>
</section>
</middle>
<back>
<!--
<references title="Normative References">
&rfc6020;
&rfc6991;
&rfc7223;
</references>
-->
<references title="Informative References">
&rfc2119;
&rfc6020;
&rfc7223;
&rfc7230;
&rfc7277;
&rfc7317;
&rfc7594;
&I-D.ietf-lmap-information-model;
&I-D.ietf-lmap-yang;
&I-D.ietf-netconf-restconf;
&I-D.ietf-netconf-call-home;
&I-D.ietf-netconf-server-model;
<!-- &I-D.starkcarey-lmap-protocol-criteria; -->
</references>
<!--
<section title="Response to Protocol Comparison Criteria">
<t>
A set of control and report protocol comparison criteria has
been defined in <xref
target="I-D.starkcarey-lmap-protocol-criteria"/>. This section
compares the usage of RESTCONF against the criteria.
<list style="hanging" hangIndent="12">
<t hangText="CP-MUST-1">
yes (RFC6241 RFC6242, RFC5539), <xref target="I-D.ietf-netconf-restconf"/>
</t>
<t hangText="CP-MUST-2">
yes <xref target="I-D.ietf-netconf-call-home"/>
</t>
<t hangText="CP-MUST-3">
yes SSH / TLS (NETCONF), TLS (RESTCONF)
</t>
<t hangText="CP-MUST-4">
yes YANG data models <xref target="RFC6020"/> have a well
defined versioning and extension model
</t>
<t hangText="CP-DIFF-1">1</t>
<t hangText="CP-DIFF-2">1</t>
<t hangText="CP-DIFF-3">yes</t>
<t hangText="CP-DIFF-4">
yes (NETCONF|RESTCONF) call home
</t>
<t hangText="CP-DIFF-5">
(underspecified - it is JSON or XML over HTTP/TLS)
</t>
<t hangText="CP-DIFF-6">
(underspecified - it is JSON or XML over HTTP/TLS)
</t>
<t hangText="CP-DIFF-7">
HTTP and JSON/XML are pretty much everywhere
</t>
<t hangText="CP-DIFF-8">
YANG tools are out there and the rest will develop, HTTP and
TLS are pretty well understood
</t>
<t hangText="CP-DIFF-9">yes</t>
<t hangText="CP-DIFF-10">many tools out there to create REST code, YANG tools available</t>
<t hangText="CP-DIFF-11">yes, YANG RFC 6020 data models have a version model</t>
<t hangText="CP-DIFF-12">additional YANG modules can augment the standard data model</t>
<t hangText="CP-DIFF-13">JSON and XML, CBOR in the making</t>
<t hangText="RP-MUST-1">yes <xref target="I-D.ietf-netconf-call-home"/></t>
<t hangText="RP-MUST-2">SSH / TLS (NETCONF), TLS (RESTCONF)</t>
<t hangText="RP-MUST-3">YANG RFC 6020 data models have a version model</t>
<t hangText="RP-DIFF-1">TCP</t>
<t hangText="RP-DIFF-2">yes</t>
<t hangText="RP-DIFF-3">(underspecified - it is HTTP over TLS)</t>
<t hangText="RP-DIFF-4">yes</t>
<t hangText="RP-DIFF-5">yes</t>
<t hangText="RP-DIFF-6">yes (as part of HTTP encoding negotiations)</t>
<t hangText="RP-DIFF-7">(underspecified - it is JSON or XML over HTTP/TLS)</t>
<t hangText="RP-DIFF-8">HTTP and JSON/XML are pretty much everywhere</t>
<t hangText="RP-DIFF-9">many tools out there to create REST code, YANG tools available</t>
<t hangText="RP-DIFF-10">yes</t>
<t hangText="RP-DIFF-11">many tools out there to create REST code, YANG tools available</t>
<t hangText="RP-DIFF-12">JSON and XML, CBOR in the making</t>
</list>
</t>
<figure>
<artwork>
<![CDATA[
]]>
</artwork>
</figure>
</section>
-->
<section anchor="ex-control" title="Example RESTCONF Control Protocol Exchange">
<t>
Below is a YANG tree diagram of a part of the data model
covering schedules. This is taken from <xref
target="I-D.ietf-lmap-yang"/>.
</t>
<figure>
<artwork>
<![CDATA[
module: ietf-lmap
+--rw lmap
+--rw schedules
+--rw schedule* [name]
+--rw name string
+--rw event leafref
+--rw action* [name]
| +--rw name string
| +--rw task leafref
| +--rw option* [name]
| | +--rw name string
| | +--rw value? string
| +--rw destination* leafref
+--rw execution-mode enumeration
]]>
</artwork>
</figure>
<t>
Below is an XML representation of instance data conforming to
the YANG data model is shown below. Note that some of the
strings are references to other portions of the instance data
not show here. This is again taken from <xref
target="I-D.ietf-lmap-yang"/>.
</t>
<figure>
<artwork>
<![CDATA[
<lmap xmlns="urn:ietf:params:xml:ns:yang:ietf-lmap">
<schedules>
<schedule>
<name>hourly-schedule</name>
<event>hourly</event>
<action>
<name>icmp-latency-hourly</name>
<task>icmp-latency-measurement</task>
<destination>daily</destination>
</action>
<execution-mode>sequential</execution-mode>
</schedule>
</schedules>
</lmap>
]]>
</artwork>
</figure>
<t>
Below is an example showing how RESTCONF can be used to create
the above schedule. The prefix C: indicates the Controller,
the prefix M: indicates the Measurement Agent. This example
uses a JSON encoding (and note that much of the white-space
can be removed, this is only there to help with readability).
</t>
<figure>
<artwork>
<![CDATA[
C: POST /restconf/data/ietf-lmap:lmap/schedules HTTP/1.1
C: Host: example.com
C: Content-Type: application/yang.data+json
C:
C: {
C: "ietf-lmap:schedule": {
C: "name": "hourly-schedule",
C: "event": "hourly",
C: "action": [
C: {
C: "name": "icmp-latency-hourly",
C: "task": "icmp-latency-measurement",
C: "destination": "daily",
C: }
C: ],
C: "execution-mode": "sequential"
C: }
C: }
M: HTTP/1.1 201 Created
M: Date: Mon, 26 Mar 2015 17:01:00 GMT
M: Server: example-server
M: Location: https://example.com/restconf/data
M: /ietf-lmap:lmap/schedules/schedule=hourly-schedule
M: Last-Modified: Mon, 26 Mar 2015 17:01:00 GMT
M: ETag: b3a3e673be2
]]>
</artwork>
</figure>
</section>
<section anchor="ex-report" title="Example RESTCONF Report Protocol Exchange">
<t>
Below is an example showing how a Measurement Agent can submit
results to a Collector running an RESTCONF server. The prefix
C: indicates the Collector, the prefix M: indicates the
Measurement Agent.
</t>
<figure>
<artwork>
<![CDATA[
M: POST /restconf/operations/ietf-lmap-report:report HTTP/1.1
M: Host: example.com
M: Content-Type: application/yang.operation+xml
M:
M: <input>
M: <report xmlns="urn:ietf:params:xml:ns:yang:ietf-lmap-report">
M: <date>2015-10-28T13:27:42+02:00</date>
M: <agent-id>550e8400-e29b-41d4-a716-446655440000</agent-id>
M: <group-id>wireless measurement at the north-pole</group-id>
M: <task>
M: <name>icmp-latency-measurement</name>
M: <metric>
M: <uri>urn:....</uri>
M: </metric>
M: <header>
M: <column>target</column>
M: <column>rtt</column>
M: </header>
M: <row>
M: <start-time>2015-03-25T00:00:55+00:00</start-time>
M: <value>192.0.2.1</value>
M: <value>42</value>
M: </row>
M: <row>
M: <start-time>2015-03-25T00:00:56+00:00</start-time>
M: <value>192.0.2.1</value>
M: <value>42</value>
M: </row>
M: </task>
M: </report>
M: </input>
C: HTTP/1.1 200 OK
]]>
</artwork>
</figure>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 02:39:52 |