LMAP Working Group D. Liu INTERNET-DRAFT L. Deng Intended Status: Standard Track China Mobile Expires: January 3, 2015 S. Duan CATR C. Li China Cache July 5, 2014 REST Style Large MeAsurement Platform Protocol draft-liu-lmap-rest-00 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 Expires January 3, 2015 [Page 1] INTERNET DRAFT July 2, 2014 (http://trustee.ietf.org/license-info) in effect on the date of 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 Control Protocol . . . . . . . . . . . . . . . . . . . . . . . . 4 3.1 Configuration Update from Controller to MA . . . . . . . . . 4 3.2 Instruction Assignment from Controller to MA . . . . . . . . 7 3.3 Capability and Status Feedback from MA to Controller . . . . 12 4 Report Protocol . . . . . . . . . . . . . . . . . . . . . . . . 14 5 Security Considerations . . . . . . . . . . . . . . . . . . . . 16 6 IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 16 8 References . . . . . . . . . . . . . . . . . . . . . . . . . . 17 9.1 Normative References . . . . . . . . . . . . . . . . . . . 17 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 18 Expires January 3, 2015 [Page 2] INTERNET DRAFT July 2, 2014 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 [RFC2616] and JSON [RFC4627] 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 January 3, 2015 [Page 3] INTERNET DRAFT July 2, 2014 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 Control Protocol The control protocol is used between controller and the measurement agent. 3.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 3.1.1 Request parameters The following are JSON parameters for the configuration update. +-------------------------------+----------------------------+ |Parameter | Type | +-------------------------------+----------------------------+ |ma-config | ma-config-obj object | Expires January 3, 2015 [Page 4] INTERNET DRAFT July 2, 2014 |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 January 3, 2015 [Page 5] INTERNET DRAFT July 2, 2014 3.1.2 Response Codes Normal Response Codes: 200 - Success Error Response Codes: 300 - Invalid request 401 - Unauthorized 422 - Unprocessable Entity 500 - Internal Server Error 3.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": "", "ma-control-tasks": [ { "ma-task-name": "", "uri": "" } ], "ma-control-channels": [ { "ma-channel-name": "", "ma-channel-target": "", "ma-channel-credientials": { } } ], "ma-control-schedules": [ { "ma-schedule-name": "", "ma-schedule-tasks": { "ma-schedule-task-name": "", "ma-schedule-task-datasets": [ { "ma-schedule-task-channel-names": [ ] } ] }, "ma-schedule-timing": { "ma-timing-name": "", "ma-timing-calendar": { "ma-calendar-minutes": "", "ma-calendar-seconds": "" }, "ma-timing-random-spread": "" } Expires January 3, 2015 [Page 6] INTERNET DRAFT July 2, 2014 } ], "ma-credentials": { } } } 3.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 3.2.1 Request parameters +-------------------------------------------------------------+ |Parameter | Type | +-----------------------------------------+-------------------+ | ma-task | object | | 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 | Expires January 3, 2015 [Page 7] INTERNET DRAFT July 2, 2014 | 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 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: Expires January 3, 2015 [Page 8] INTERNET DRAFT July 2, 2014 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 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. 3.2.2 Response codes Normal Response Codes: 200 - Success Error Response Codes: 300 - Invalid request 401 - Unauthorized 422 - Unprocessable Entity 500 - Internal Server Error 3.2.3 JSON Request Expires January 3, 2015 [Page 9] INTERNET DRAFT July 2, 2014 { "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":"", "ma-task-options":"", "ma-task-cycle-id":"" }, ... ], "ma-schedule-timing":{ Expires January 3, 2015 [Page 10] INTERNET DRAFT July 2, 2014 "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":""}, { "task-name":""}, ... ], "ma-suppression-schedule-names":[ { "schedule-name":""}, { "schedule-name":""}, Expires January 3, 2015 [Page 11] INTERNET DRAFT July 2, 2014 ... ] } } 3.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. 3.3.1 Request GET /ma/capabilities Get failure information API: GET /ma/failure Get logging information API: Get /ma/logging 3.3.2 Response Codes Normal Response Codes: 200 - Success Error Response Codes: 300 - Invalid request 401 - Unauthorized 422 - Unprocessable Entity 500 - Internal Server Error 3.3.3 Response The get status and capabilities response message is in JSON format: Parameters format: +--------------------+-----------+ |Parameter | Type | |--------------------+-----------+ |ma-agent-id | string | +--------------------+-----------+ |ma-device-id | string | +--------------------+-----------+ |ma-hardware | string | +--------------------+-----------+ |ma-firmware | string | +--------------------+-----------+ |ma-version | string | Expires January 3, 2015 [Page 12] INTERNET DRAFT July 2, 2014 +--------------------+-----------+ |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": [ { "ma-task-name": "", "ma-task-registry": "" }, { "ma-task-name": "", "ma-task-registry": "" }, { "ma-task-name": "", "ma-task-registry": "" Expires January 3, 2015 [Page 13] INTERNET DRAFT July 2, 2014 }, { "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":"" } 4 Report Protocol 4.1 Report request API: POST /collector/report/ 4.2 Response code Normal Response Codes: 200 - Success Error Response Codes: 300 - Invalid request 401 - Unauthorized 422 - Unprocessable Entity 500 - Internal Server Error 4.3 Response JSON: Parameter format: +--------------------+-----------+ |Parameter | Type | |--------------------+-----------+ |ma-report-date | string | +--------------------+-----------+ |ma-report-agent-id | string | Expires January 3, 2015 [Page 14] INTERNET DRAFT July 2, 2014 +--------------------+-----------+ |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": [ { "ma-report-task-config": { "ma-task-name": "", "ma-task-registry": "", "ma-task-options": [ { "name": "", "value": "" }, { "name": "", Expires January 3, 2015 [Page 15] INTERNET DRAFT July 2, 2014 "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": "" } ] } 5 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. 6 IANA Considerations There is no IANA action in this document. Expires January 3, 2015 [Page 16] INTERNET DRAFT July 2, 2014 8 References 9.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-06 (work in progress), June 2014. [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-01 (work in progress), February 2014. ti 0 7.2 Informative References [RFC 2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. [RFC 4627] Crockford, D., "The application/json Media Type for JavaScript Object Notation (JSON)", RFC 4627, July 2006. Expires January 3, 2015 [Page 17] INTERNET DRAFT July 2, 2014 Authors' Addresses Dapeng Liu China Mobile Email: liudapeng@chinamobile.com Lingli Deng China Mobile Email: denglingli@chinamobile.com Shihui Duan CATR of MIIT Email: duanshihui@catr.cn Cathy Li China Cache Email: cathy.li@chinacache.com Expires January 3, 2015 [Page 18]