LMAP Working Group V. Liu INTERNET-DRAFT L. Deng Intended Status: Standard Track China Mobile Expires: September 9, 2015 S. Liu CATR C. Li China Cache March 8, 2015 REST Style Large MeAsurement Platform Protocol draft-liu-lmap-rest-02 Abstract This document defines a REST-style protocols for Large Scale Performance Measurement (LMAP). Status of this Memo This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/1id-abstracts.html The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html Copyright and License Notice Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of Expires Sep 9, 2015 [Page 1] INTERNET DRAFT Mar 8, 2015 publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3 Protocol Implementation Consideration . . . . . . . . . . . . . 4 3.1 The Side that Initiates Control Session . . . . . . . . . . 4 3.2 the Side that initiates Report Session . . . . . . . . . . . 4 3.3 the Advantages of REST . . . . . . . . . . . . . . . . . . . 5 4 Control Protocol . . . . . . . . . . . . . . . . . . . . . . . . 5 4.1 Configuration Update from Controller to MA . . . . . . . . . 5 4.2 Instruction Assignment from Controller to MA . . . . . . . . 8 4.3 Capability and Status Feedback from MA to Controller . . . . 13 5 Report Protocol . . . . . . . . . . . . . . . . . . . . . . . . 15 6 Security Considerations . . . . . . . . . . . . . . . . . . . . 17 7 IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 17 8 References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 8.1 Normative References . . . . . . . . . . . . . . . . . . . 18 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 19 Expires Sep 9, 2015 [Page 2] INTERNET DRAFT Mar 8, 2015 1 Introduction With the rapid development of Internet technology and the increasing complexity of broadband network architecture, it is quite difficult to do large scale network measurements due to the lack of the unified measurement system and cooperative protocols. Therefore, the Large- Scale Measurement of Broadband Performance (LMAP) working group is formed to standardize a large scale measurement system for performance measurements of all kinds of broadband access methods. There are 3 types of entities proposed in the LMAP architecture: [I- D.ietf-lmap-framework] o Measurement Agents (MAs), implemented in network to perform measurement tasks; o Controller, responsible for creating and assigning the measurement tasks; and o Collector, in charge of collecting and storing measurement results. This document presents REST-style protocols for LMAP based on the information model from [I-D.ietf-lmap-information-model]. 2 Terminology 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 RFC 2119 [RFC2119]. This document follows the standardized HTTP/1.1 [RFC7213] and JSON [RFC7159] specifications. REST: Representational State Transfer The following terms used in this document are defined in [I-D.ietf- lmap-framework]. o Bootstrap o Channel o Collector o Controller o Control Channel Expires Sep 9, 2015 [Page 3] INTERNET DRAFT Mar 8, 2015 o Control Protocol o Data Model o Instruction o Measurement Agent (MA) o Measurement Peer (MP) o Measurement Schedule o Measurement Task o Measurement Traffic o Report o Report Channel o Report Protocol o Report Schedule o Subscriber 3 Protocol Implementation Consideration 3.1 The Side that Initiates Control Session It is expected that the control session can be initiated by the controller or MA, but in this document, it is the controller that initiates the control session for the following considerations: o On one hand, if the initiation is from Controller side, the session can be started almost instantly, without the considering the polling time of all the MAs, and making a lot effort to synchronization the start moment. o on the other hand, since Controller initiates the session, it can periodically poll the MA to detect the activation state. However, when the corresponding MA locates behind a NAT/FW while the controller is located outside of the NAT/FW, the NAT/FW traversal techniques should be employed such as STUN/TURN or port forwarding. 3.2 the Side that initiates Report Session Expires Sep 9, 2015 [Page 4] INTERNET DRAFT Mar 8, 2015 It is assumed that the report session can be initiated by the MA [RP- MUST-1, draft-starkcarey-lmap-protocol-criteria-01], so the report can be sent in real time. 3.3 the Advantages of REST This document follows the REST style in designing both the control and report protocols for LMAP, for the following considerations: First, REST is much easier to be implemented the other methods such as SOAP, most of open source web service developing packages support REST, to deploy a REST application can be as easy as a few lines of code [CP-DIFF-7, CP-DIFF-9, CP-DIFF-10, RP-DIFF-10, RP-DIFF-11, draft-starkcarey-lmap-protocol-criteria-01]. Second, no special requirement for the client, any browser or http client can visit the REST application. Last, REST has clear resource annotation and finite operations, all of those are readable, and easy to understand [CP-MUST-4, RP-MUST-3, draft-starkcarey-lmap-protocol-criteria-01]. 4 Control Protocol The control protocol is used between controller and the measurement agent. 4.1 Configuration Update from Controller to MA Configuration allows the Controller to update the MA about some or all of the information that it obtained during the bootstrapping process: the MA-ID, the (optional) Group-ID and the Control Channel. The configuration update REST-style protocol is defined to convey the configuration information from the Controller to the MA, via a HTTP PUT, as described below. PUT /ma/config/ Update the configuration from controller to MA 4.1.1 Request parameters The following are JSON parameters for the configuration update. +-------------------------------+----------------------------+ |Parameter | Type | +-------------------------------+----------------------------+ Expires Sep 9, 2015 [Page 5] INTERNET DRAFT Mar 8, 2015 |ma-config | ma-config-obj object | |ma-agent-id | string | |ma-control-tasks | ma-control-task object | |ma-task-name | string | |uri | string | |ma-control-channels | ma-channel-obj object | |ma-channel-name | string | |ma-channel-target | string | |ma-channel-credientials | channel credential object | |ma-control-schedules | ma-schedule-obj object | |ma-schedule-name | string | |ma-schedule-tasks | ma-sched-task-obj object | |ma-schedule-task-name | string | |ma-schedule-task-datasets | ma-sched-dataset-obj object| |ma-schedule-task-channel-names | string | |ma-schedule-timing | ma-timing-obj object | |ma-timing-name | string | |ma-timing-calendar | ma-calendar-obj object | |ma-calendar-minutes | number | |ma-calendar-seconds | number | |ma-timing-random-spread | number | |ma-credentials | credentials object | +-------------------------------+----------------------------+ o ma-agent-id: the assigned ID of the MA. o ma-control-tasks: the configuration of the control channel to be used between the Controller and the MA, which includes the following parameters: o ma-task-name: the string name of the task o uri: the uri of the task o ma-channel-name: the string name of the channel. o ma-channel-target: the URL of the Controller to be contacted by the MA. o ma-channel-credientials: the channel credentials object. o ma-control-schedules: the MA schedule object. o ma-schedule-name: the string name of the schedule. o ma-schedule-tasks: the MA schedule task object. o ma-schedule-task-name: the string name of the MA schedule task. o ma-schedule-task-datasets: the MA shedule task object. o ma-schedule-task-channel-names: the string name of task channel. o ma-schedule-timing: the MA timing object. o ma-timing-name: the string name of the MA timing. o ma-timing-calendar: the MA timing calendar obejct. o ma-calendar-minutes: minutes number. o ma-calendar-seconds: seconds number. o ma-timing-random-spread: the random spread of the MA timing. o ma-credentials: the MA credentials object. Expires Sep 9, 2015 [Page 6] INTERNET DRAFT Mar 8, 2015 4.1.2 Response Codes Normal Response Codes: 200 Error Response Codes: 404 4.1.3 JSON Request The following is an example of JSON request for an HTTP PUT request for MA configuration. { "ma-config": { "ma-agent-id": "550e8400-e29b-41d4-a716-446655440000", "ma-control-tasks": [ { "ma-task-name": "Controller configuration", "ma-task-registry-entry": "urn:ietf:lmap:control:http_controller_configuration" }, { "ma-task-name": "Controller status and capabilities", "ma-task-registry-entry": "urn:ietf:lmap:control:http_controller_status_and_capabilities" }, { "ma-task-name": "Controller instruction", "ma-task-registry-entry": "urn:ietf:lmap:control:http_controller_instruction" } ] "ma-control-channels": [ { "ma-channel-name": "Controller instruction", "ma-channel-target": "http://www.example.com/lmap/controller", "ma-channel-credientials": { } } ] "ma-control-schedules": [ { "ma-schedule-name": "Controller schedule", "ma-schedule-tasks": [ { "ma-schedule-task-name": "Controller configuration", "ma-schedule-channels": [ { "ma-schedule-channel-interface-selection": [1], "ma-schedule-task-source-channel-names": ["Controller channel"] } ] }, { Expires Sep 9, 2015 [Page 7] INTERNET DRAFT Mar 8, 2015 "ma-schedule-task-name": "Controller status and capabilities", "ma-schedule-channels": [ { "ma-schedule-channel-interface-selection": [1], "ma-schedule-task-source-channel-names": ["Controller channel"] } ] }, { "ma-schedule-task-name": "Controller instruction", "ma-schedule-channels": [ { "ma-schedule-channel-interface-selection": [1], "ma-schedule-task-source-channel-names": ["Controller channel"] } ] } ] "ma-schedule-timing": { "ma-timing-name": "hourly randomly", "ma-timing-calendar": { "ma-calendar-minutes": ["00"], "ma-calendar-seconds": ["00"] } "ma-timing-random-spread": "3600000" } } ] "ma-credentials": { } } } 4.2 Instruction Assignment from Controller to MA The Instruction is the description of the Measurement Tasks for a Measurement Agent to do and the details of the Measurement Reports for it to send, which is realized by a HTTP POST transaction. POST /ma/ins/ Send measurement instruction from controller to MA 4.2.1 Request parameters +-------------------------------------------+-------------------+ |Parameter | Type | +-------------------------------------------+-------------------+ | ma-task | object | Expires Sep 9, 2015 [Page 8] INTERNET DRAFT Mar 8, 2015 | ma-task-name | string | | ma-task-registry | string | | ma-task-options | object | | ma-task-cycle-id (optional) | number | | ma-schedule | string | | ma-schedule-name | string | | ma-schedule-tasks | string | | ma-schedule-task-name | string | | ma-schedule-task-reports | string | | ma-schedule-task-filter (optional) | number | | ma-schedule-task-report-channel-name | string | | ma-task-options | string | | ma-task-cycle-id (optional) | number | | ma-channel | string | | ma-channel-name | string | | ma-channel-target | string | | ma-channel-timing | string | | ma-timing-name (optional) | string | | ma-timing-arrangement | string | | ma-timing-periodic | string | | ma-periodic-start(optional) | number | | ma-periodic-end(optional) | number | | ma-periodic-interval | number | | ma-timing-calendar | string | | ma-timing-one-off | string | | ma-timing-immediate | string | | ma-timing-randomness | string | | ma-channel-interface-name | string | | ma-channel-connect-always(optional) | bool | | ma-suppression | string | | ma-suppression-enabled | bool | | ma-suppression-start (optional) | string | | ma-suppression-end (optional) | string | | ma-suppression-task-names (optional) | object | | ma-suppression-schedule-names(optional) | object | +-------------------------------------------+-------------------+ o ma-tasks: the list of measurement tasks contained in the instruction, where each measurement task contains the following four parameters: o ma-task-name: the string name for a specific measurement task, to be used as reference in other places, such as measurement schedules and suppressions. o ma-task-registry: the URN (Uniform Resource Name) of the measurement task as defined by [I- D.draft-ippm-registry]. o ma-task-options: the list of input parameters that are to be used when performing the measurement task, which are specific to each measurement task in question and defined by [I-D.draft-ippm- registry]. o ma-task-cycle-id(optional): the identification ID for a group of measurement tasks with comparable Expires Sep 9, 2015 [Page 9] INTERNET DRAFT Mar 8, 2015 options, which is manually incremented when an Option change is implemented which could mean that two sets of results should not be directly compared. o ma-schedules: the list of measurement schedules in the instruction, where each measurement schedule contains the following parameters: o ma-schedule-name: the string name for a specific measurement schedule, to be used as reference in other places, such as suppressions. o ma-schedule-tasks: the list of measurement tasks to be performed for this schedule, where each scheduled measurement task contains the following parameter in addition to its name, options and cycle-id: o ma-schedule-task- reports: the report channel settings for the measurement reporting, which in turn contains an optional filter configuration for a specified group (default is all) of measurement output to a named report channel. o ma-channel: the report channel to be used by the measurement schedules to configure the measurement reporting for the instruction, which is also used to define the control channel by configuration request from Controller to the MA. o ma-channel-name: the sting name of the channel. o ma-channel-target: the URL of the Controller to be contacted by the MA. o ma-channel-timing: the timing arrangements indicating when to contact the Controller by the MA, whose in turn includes the following parameters: o ma-timing- name(optional): the string name of the time setting. o ma-timing- arrangement: the arrangements for the timing of Controller communications, whose value can be one of the following parameters: o ma-timing-periodic: the periodic timing arrangement for the Controller communications, which in turn includes the following parameters: o ma-periodic-start(optional): the time of the day (in miliseconds) when the communication starts. If absent, the period starts immediately. o ma-periodic-end(optional): the time of day (in miliseconds) when the communication ends. If absent, the communication is not stopped unless the MA is otherwise instructed. o ma-periodic-interval: the interval time (in miliseconds) of periodic communications. o ma-timing-calendar: the communication happens according to a calendar-like timing arrangements. o ma-timing-one-off: the communication happens once and for all. o ma-timing-immediate: the communication happens immediately. o ma-timing-randomness: the randomness configuration to be added onto each communication event. o ma-channel-interface-name: the name of MA's interface to be used when contacting the Controller. o ma- channel-connect-always: the indicator whether or not to keep the connection to the Controller. If absent, the connection is reopened whenever new communication is pending and closed when it is over. o ma-suppression: the measurement tasks/schedules to be suppressed by the instruction. In addition to the lists of measurement tasks/schedules, it also contains the following parameters: o ma- suppression-enabled(optional): The bool indicator of whether or not Expires Sep 9, 2015 [Page 10] INTERNET DRAFT Mar 8, 2015 to enable the local suppression by the MA. For example, a later unsuppression to an earlier suppression instruction can be achieved by setting this indicator to 'false'. Default is false. o ma- suppression-start(optional): The time when to start the suppression action. Default is immediate. o ma-suppression-end(optional): The time when to end the suppression action. Default is infinite. 4.2.2 Response codes Normal Response Codes: 200 Error Response Codes: 400 4.2.3 JSON Request { "ma-task": { "ma-task-name":"", "ma-task-registry":"", "ma-task-options":"", "ma-task-cycle-id":"" }, "ma-schedule:{ "ma-schedule-name":"", "ma-schedule-tasks":[{ "ma-task-name":"", "ma-task-registry":"", "ma-task-options":"", "ma-task-cycle-id":"" }, { "ma-task-name":"", "ma-task-registry":"", Expires Sep 9, 2015 [Page 11] INTERNET DRAFT Mar 8, 2015 "ma-task-options":"", "ma-task-cycle-id":"" }, ... ], "ma-schedule-timing":{ "ma-timing-periodic":"", "ma-timing-randomness":"" } }, "ma-channel":{ "ma-channel-name":"", "ma-channel-target":"", "ma-channel-certificate":"", "ma-channel-timing":"", "ma-channel-interface-name":"", "ma-channel-connect-always":"" }, "ma-suppression":{ "ma-suppression-enabled":"", "ma-suppression-start":"", "ma-suppression-end":"", "ma-suppression-task-names":[ { "task-name":""}, Expires Sep 9, 2015 [Page 12] INTERNET DRAFT Mar 8, 2015 { "task-name":""}, ... ], "ma-suppression-schedule-names":[ { "schedule-name":""}, { "schedule-name":""}, ... ] } } 4.3 Capability and Status Feedback from MA to Controller Capability and status feedback is returned to the Controller from the MA whenever requested, which is implemented by an HTTP Get transaction. 4.3.1 Request GET /ma/capabilities Get failure information API: GET /ma/failure Get logging information API: GET /ma/logging 4.3.2 Response Code Code 200 for success. Code 400 for failure. 4.3.3 Response The get status and capabilities response message is in JSON format: Parameters format: +--------------------+-----------+ |Parameter | Type | |--------------------+-----------+ Expires Sep 9, 2015 [Page 13] INTERNET DRAFT Mar 8, 2015 |ma-agent-id | string | +--------------------+-----------+ |ma-device-id | string | +--------------------+-----------+ |ma-hardware | string | +--------------------+-----------+ |ma-firmware | string | +--------------------+-----------+ |ma-version | string | +--------------------+-----------+ |ma-interface-name | string | +--------------------+-----------+ |ma-interface-type | string | +--------------------+-----------+ |ma-last-measurement | string | +--------------------+-----------+ |ma-last-report | string | +--------------------+-----------+ |ma-last-instruction | string | +--------------------+-----------+ |ma-last- | | |configuration | string | +--------------------+-----------+ |ma-task-name | string | +--------------------+-----------+ |ma-task-registry | string | +--------------------+-----------+ JSON format: { "ma-status-and-capabilities": { "ma-agent-id": "", "ma-device-id": "", "ma-hardware": "", "ma-firmware": "", "ma-version": "", "ma-interfaces": [ { "ma-interface-name": "", "ma-interface-type": "" } ], "ma-last-measurement": "", "ma-last-report": "", "ma-last-instruction": "", "ma-last-configuration": "", "ma-supported-tasks": [ { Expires Sep 9, 2015 [Page 14] INTERNET DRAFT Mar 8, 2015 "ma-task-name": "", "ma-task-registry": "" }, { "ma-task-name": "", "ma-task-registry": "" }, { "ma-task-name": "", "ma-task-registry": "" }, { "ma-task-name": "", "ma-task-registry": "" }, { "ma-task-name": "", "ma-task-registry": "" } ] } } The response of get failure information API is in JSON format: { "failure code 1":"no spare CPU cycles", "failure code 2":"out of spare memory", "failure code 3":"collector is not responding", ... } The response of get logging information API is as follows: { "ma-log-agent-id":"", "ma-log-event-time": "", "ma-log-code":"", "ma-log-description":"" } 5 Report Protocol 5.1 Report Request API: POST /collector/report/ 5.2 Response Code Code 200 for success. Code 400 for failure. Expires Sep 9, 2015 [Page 15] INTERNET DRAFT Mar 8, 2015 5.3 Response JSON: Parameter format: +--------------------+-----------+ |Parameter | Type | |--------------------+-----------+ |ma-report-date | string | +--------------------+-----------+ |ma-report-agent-id | string | +--------------------+-----------+ |ma-report-group-id | string | +--------------------+-----------+ |ma-task-name | string | +--------------------+-----------+ |ma-task-registry | string | +--------------------+-----------+ |name | string | +--------------------+-----------+ |value | string | +--------------------+-----------+ |ma-task-suppress- | string | | by-default | | +--------------------+-----------+ |ma-task-cycle-id | string | +--------------------+-----------+ |ma-report-task- | string | | column-labels | | +--------------------+-----------+ |ma-report-result- | string | | time | | +--------------------+-----------+ | ma-report- | | | conflicting-tasks | string | +--------------------+-----------+ |ma-report-result- | | | cross-traffic | string | +--------------------+-----------+ |ma-report-result- | | | values | string | +--------------------+-----------+ Response JSON: { "ma-report-date": "", "ma-report-agent-id": "", "ma-report-group-id": "", "ma-report-tasks": [ { Expires Sep 9, 2015 [Page 16] INTERNET DRAFT Mar 8, 2015 "ma-report-task-config": { "ma-task-name": "", "ma-task-registry": "", "ma-task-options": [ { "name": "", "value": "" }, { "name": "", "value": "" } ] } } ], "ma-task-suppress-by-default": "", "ma-task-cycle-id": "", "ma-report-task-column-labels": [ ], "ma-report-task-rows": [ { "ma-report-result-time": "", "ma-report-conflicting-tasks": "", "ma-report-result-cross-traffic": "", "ma-report-result-values": "" } ] } 6 Security Considerations The REST API could be protected by several ways. One common solution is to provide authentication mechanism for all the HTTP request. Encryption mechanism could also be provided by HTTPS, the credential can be employed for authentication. 7 IANA Considerations There is no IANA action in this document. Expires Sep 9, 2015 [Page 17] INTERNET DRAFT Mar 8, 2015 8 References 8.1 Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [I-D.ietf-lmap-framework] Eardley, P., Morton, A., Bagnulo, M., Burbridge, T., Aitken, P., and A. Akhter, "A framework for large-scale measurement platforms (LMAP)", draft-ietf- lmap-framework-11 (work in progress), Feburary 2015. [I-D.ietf-lmap-information-model] Burbridge, T., Eardley, P., Bagnulo, M., and J. Schoenwaelder, "Information Model for Large-Scale Measurement Platforms (LMAP)", draft-ietf- lmap-information-model-03 (work in progress), January 2015. [RFC7213] R. Fielding, J. Reschke "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content" [RFC7159] T. Bray, "The JavaScript Object Notation (JSON) Data Interchange Format" [draft-starkcarey-lmap-protocol-criteria-01] B. Stark, T. Carey "LMAP Protocol Selection Criteria" Expires Sep 9, 2015 [Page 18] INTERNET DRAFT Mar 8, 2015 Authors' Addresses Vic Liu China Mobile Email: liuzhiheng@chinamobile.com Lingli Deng China Mobile Email: denglingli@chinamobile.com Shu Liu China Academy of Information and Communication Technology Email: liushu@catr.cn Cathy Li China Cache Email: cathy.li@chinacache.com Expires Sep 9, 2015 [Page 19]