idnits 2.17.1 draft-ietf-lmap-restconf-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 1 character in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 234 has weird spacing: '...on-mode enum...' == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (July 8, 2016) is 2848 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-12) exists of draft-ietf-lmap-yang-04 == Outdated reference: A later version (-18) exists of draft-ietf-netconf-restconf-14 == Outdated reference: A later version (-18) exists of draft-ietf-lmap-information-model-09 -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 1 error (**), 0 flaws (~~), 6 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Schoenwaelder 3 Internet-Draft V. Bajpai 4 Intended status: Standards Track Jacobs University Bremen 5 Expires: January 9, 2017 July 8, 2016 7 Using RESTCONF with LMAP Measurement Agents 8 draft-ietf-lmap-restconf-03.txt 10 Abstract 12 This document describes how RESTCONF can be used with a YANG data 13 model for Large-Scale Measurement Platforms (LMAP). 15 Status of This Memo 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF). Note that other groups may also distribute 22 working documents as Internet-Drafts. The list of current Internet- 23 Drafts is at http://datatracker.ietf.org/drafts/current/. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 This Internet-Draft will expire on January 9, 2017. 32 Copyright Notice 34 Copyright (c) 2016 IETF Trust and the persons identified as the 35 document authors. All rights reserved. 37 This document is subject to BCP 78 and the IETF Trust's Legal 38 Provisions Relating to IETF Documents 39 (http://trustee.ietf.org/license-info) in effect on the date of 40 publication of this document. Please review these documents 41 carefully, as they describe your rights and restrictions with respect 42 to this document. Code Components extracted from this document must 43 include Simplified BSD License text as described in Section 4.e of 44 the Trust Legal Provisions and are provided without warranty as 45 described in the Simplified BSD License. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 50 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 2 51 2. Overview of RESTCONF . . . . . . . . . . . . . . . . . . . . 3 52 3. RESTCONF as LMAP Control Protocol . . . . . . . . . . . . . . 3 53 4. RESTCONF as LMAP Report Protocol . . . . . . . . . . . . . . 3 54 5. RESTCONF Configuration for LMAP . . . . . . . . . . . . . . . 4 55 6. Security Considerations . . . . . . . . . . . . . . . . . . . 4 56 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4 57 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 4 58 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 4 59 9.1. Normative References . . . . . . . . . . . . . . . . . . 4 60 9.2. Informative References . . . . . . . . . . . . . . . . . 4 61 Appendix A. Example RESTCONF Control Protocol Exchange . . . . . 5 62 Appendix B. Example RESTCONF Report Protocol Exchange . . . . . 7 63 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 65 1. Introduction 67 This document discusses how a Controller can use the RESTCONF 68 protocol [I-D.ietf-netconf-restconf] to configure Large-Scale 69 Measurement of Broadband Performance (LMAP) Measurement Agents 70 [RFC7594]. It also discusses how RESTCONF can be used by a 71 Measurement Agent to report measurement results to a Collector. 73 Measurement Agents may be deployed as separate hardware devices or as 74 functions embedded in consumer electronic devices and home routers or 75 as pure software solutions that can be installed on off-the-shelf 76 computing equipment. Measurement Agents receive instructions from a 77 Controller about when and how to conduct what measurements (the 78 measurement schedule) and how and when to report measurement results 79 to a data Collector (the report schedule). Further information about 80 the interaction between Measurement Agents and Controllers and 81 Collectors can be found in [RFC7594]. 83 The LMAP information model [I-D.ietf-lmap-information-model] defines 84 the information exchanged between a Controller and an Measurement 85 Agent and the information exchanged between an Measurement Agent and 86 a Collector. An information model is conceptual and protocol- 87 independent. A concrete YANG [RFC6020] data model derived from the 88 conceptual information model is defined in [I-D.ietf-lmap-yang]. 90 1.1. Terminology 92 This document uses the LMAP terminology defined in [RFC7594]. 94 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 95 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 96 document are to be interpreted as described in [RFC2119]. 98 2. Overview of RESTCONF 100 The RESTCONF protocol [I-D.ietf-netconf-restconf] provides a REST- 101 like interface to access and manipulate a so-called unified YANG 102 datastore [RFC6020]. The basic idea behind RESTCONF is expose a YANG 103 datastores as a collection of Web resources that can be manipulated 104 using standard HTTP [RFC7230] DELETE, PATCH, POST, and PUT methods. 105 The resource hierarchy is derived from the nesting structure of the 106 YANG schema tree, leading to a so-called data model driven REST API. 108 RESTCONF is essentially a convention how to use HTTP over TLS to 109 access a datastore that has a structure defined by a YANG data model. 110 The data is exchanged in XML encoding or JSON encoding. 112 The normal mode of operation is that the RESTCONF client initiates a 113 secure transport to the RESTCONF server. For devices located behind 114 a NAT, a so called 'call-home' mechanism has been defined 115 [I-D.ietf-netconf-call-home] that enables the RESTCONF server to 116 establish a secure transport to a RESTCONF client. Note that call 117 home only changes the TCP connection establishment, the TLS and HTTP 118 client/server roles do not change. The policy used to call home can 119 be configured through a configuration data model 120 [I-D.ietf-netconf-server-model]. This model provides a mechanism to 121 configure a list of redundant endpoints and it provides control over 122 call-home policies (e.g, call-home frequency, idle-timers, keep-alive 123 timers). 125 3. RESTCONF as LMAP Control Protocol 127 It is straight-forward to use RESTCONF as a control protocol. The 128 YANG data model [I-D.ietf-lmap-yang] derived from the underlying 129 information model [I-D.ietf-lmap-information-model] translates into a 130 collection of RESTCONF resources that can be manipulated at various 131 levels of granularity using DELETE, PATCH, POST, and PUT methods. 133 An example exchange showing a REST call to create a schedule object 134 is shown in Appendix A. 136 4. RESTCONF as LMAP Report Protocol 138 For reporting results from the Measurement Agent to a Collector, the 139 Collector is assumed to act as a RESTCONF server. The Measurement 140 Agent pushes results to the Collector by invoking an operation on the 141 Controller. 143 5. RESTCONF Configuration for LMAP 145 XXX: This section should explain how an LMAP implementation needs to 146 be configured to make use of the call-home mechanism and how report 147 tasks refer to the configuration (if any standardized) needed to 148 obtain the necessary credentials to report results. This needs to be 149 worked through in detail. 151 6. Security Considerations 153 TBD 155 7. IANA Considerations 157 This document has no requests for IANA. 159 8. Acknowledgements 161 Juergen Schoenwaelder and Vaibhav Bajpai worked in part on the Leone 162 research project, which received funding from the European Union 163 Seventh Framework Programme [FP7/2007-2013] under grant agreement 164 number 317647. 166 Juergen Schoenwaelder and Vaibhav Bajpai were partly funded by 167 Flamingo, a Network of Excellence project (ICT-318488) supported by 168 the European Commission under its Seventh Framework Programme. 170 9. References 172 9.1. Normative References 174 [I-D.ietf-lmap-yang] 175 Schoenwaelder, J. and V. Bajpai, "A YANG Data Model for 176 LMAP Measurement Agents", draft-ietf-lmap-yang-04 (work in 177 progress), March 2016. 179 [I-D.ietf-netconf-restconf] 180 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 181 Protocol", draft-ietf-netconf-restconf-14 (work in 182 progress), June 2016. 184 9.2. Informative References 186 [I-D.ietf-lmap-information-model] 187 Burbridge, T., Eardley, P., Bagnulo, M., and J. 188 Schoenwaelder, "Information Model for Large-Scale 189 Measurement Platforms (LMAP)", draft-ietf-lmap- 190 information-model-09 (work in progress), March 2016. 192 [I-D.ietf-netconf-call-home] 193 Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 194 draft-ietf-netconf-call-home-17 (work in progress), 195 December 2015. 197 [I-D.ietf-netconf-server-model] 198 Watsen, K. and J. Schoenwaelder, "NETCONF Server and 199 RESTCONF Server Configuration Models", draft-ietf-netconf- 200 server-model-09 (work in progress), March 2016. 202 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 203 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 204 RFC2119, March 1997, 205 . 207 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 208 the Network Configuration Protocol (NETCONF)", RFC 6020, 209 DOI 10.17487/RFC6020, October 2010, 210 . 212 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 213 Protocol (HTTP/1.1): Message Syntax and Routing", RFC 214 7230, DOI 10.17487/RFC7230, June 2014, 215 . 217 [RFC7594] Eardley, P., Morton, A., Bagnulo, M., Burbridge, T., 218 Aitken, P., and A. Akhter, "A Framework for Large-Scale 219 Measurement of Broadband Performance (LMAP)", RFC 7594, 220 DOI 10.17487/RFC7594, September 2015, 221 . 223 Appendix A. Example RESTCONF Control Protocol Exchange 225 Below is a YANG tree diagram of a part of the data model covering 226 schedules. This is taken from [I-D.ietf-lmap-yang]. 228 module: ietf-lmap-control 229 +--rw lmap 230 +--rw schedules 231 +--rw schedule* [name] 232 +--rw name lmap:identifier 233 +--rw event event-ref 234 +--rw execution-mode enumeration 235 +--rw action* [name] 236 +--rw name string 237 +--rw task task-ref 238 +--rw option* [name] 239 | +--rw id lmap:identifier 240 | +--rw name? string 241 | +--rw value? string 242 +--rw destination* leafref 244 Below is an XML representation of instance data conforming to the 245 YANG data model is shown below. Note that some of the strings are 246 references to other portions of the instance data not show here. 247 This is again taken from [I-D.ietf-lmap-yang]. 249 250 251 252 hourly-schedule 253 hourly 254 sequential 255 256 icmp-latency-hourly 257 icmp-latency-measurement 258 daily 259 260 261 262 264 Below is an example showing how RESTCONF can be used to create the 265 above schedule. The prefix C: indicates the Controller, the prefix 266 M: indicates the Measurement Agent. This example uses a JSON 267 encoding (and note that much of the white-space can be removed, this 268 is only there to help with readability). 270 C: POST /restconf/data/ietf-lmap-control:lmap/schedules HTTP/1.1 271 C: Host: example.com 272 C: Content-Type: application/yang.data+json 273 C: 274 C: { 275 C: "ietf-lmap-control:schedule": { 276 C: "name": "hourly-schedule", 277 C: "event": "hourly", 278 C: "execution-mode": "sequential", 279 C: "action": [ 280 C: { 281 C: "name": "icmp-latency-hourly", 282 C: "task": "icmp-latency-measurement", 283 C: "destination": "daily", 284 C: } 285 C: ] 286 C: } 287 C: } 289 M: HTTP/1.1 201 Created 290 M: Date: Mon, 26 Mar 2015 17:01:00 GMT 291 M: Server: example-server 292 M: Location: https://example.com/restconf/data 293 M: /ietf-lmap-control:lmap/schedules/schedule=hourly-schedule 294 M: Last-Modified: Mon, 26 Mar 2015 17:01:00 GMT 295 M: ETag: b3a3e673be2 297 Appendix B. Example RESTCONF Report Protocol Exchange 299 Below is an example showing how a Measurement Agent can submit 300 results to a Collector running an RESTCONF server. The prefix C: 301 indicates the Collector, the prefix M: indicates the Measurement 302 Agent. 304 M: POST /restconf/operations/ietf-lmap-report:report HTTP/1.1 305 M: Host: example.com 306 M: Content-Type: application/yang.operation+xml 307 M: 308 M: 309 M: 2015-10-28T13:27:42+02:00 310 M: 550e8400-e29b-41d4-a716-446655440000 311 M: wireless measurement at the north-pole 312 M: 313 M: pinger 314 M: fping 315 M: fping 316 M: 320 M: 324 M: 329 M: 333 M: 337 M: 341 M: 2016-03-21T10:48:55+01:00 342 M: 2016-03-21T10:48:57+01:00 343 M: 0 344 M: 345 M: target 346 M: ip 347 M: rtt-1 348 M: rtt-2 349 M: rtt-3 350 M: rtt-4 351 M: rtt-5 352 M: 353 M: www.example.org 354 M: 2001:db8::1 355 M: 14.15 356 M: 14.14 357 M: 14.09 358 M: 14.17 359 M: 14.51 360 M: 361 M: 362 M: mail.example.org 363 M: 2001:db8::2 364 M: 12.24 365 M: 11.99 366 M: 12.49 367 M: 11.87 368 M: 12.45 369 M: 370 M:
371 M: 372 M: 374 C: HTTP/1.1 200 OK 376 Authors' Addresses 378 Juergen Schoenwaelder 379 Jacobs University Bremen 381 Email: j.schoenwaelder@jacobs-university.de 383 Vaibhav Bajpai 384 Jacobs University Bremen 386 Email: v.bajpai@jacobs-university.de