LMAP Working Group D. Liu
INTERNET-DRAFT L. Deng
Intended Status: Standard Track China Mobile
Expires: January 3, 2015 S. Liu
CATR
C. Li
China Cache
Oct 27, 2014
REST Style Large MeAsurement Platform Protocol
draft-liu-lmap-rest-01
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
<Liu, et al.> Expires January 3, 2015 [Page 1]
INTERNET DRAFT <Rest for LMAP> 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
<Liu, et al.> Expires January 3, 2015 [Page 2]
INTERNET DRAFT <Rest for LMAP> 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
<Liu, et al.> Expires January 3, 2015 [Page 3]
INTERNET DRAFT <Rest for LMAP> 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 |
<Liu, et al.> Expires January 3, 2015 [Page 4]
INTERNET DRAFT <Rest for LMAP> July 2, 2014
+-------------------------------+----------------------------+
|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.
<Liu, et al.> Expires January 3, 2015 [Page 5]
INTERNET DRAFT <Rest for LMAP> July 2, 2014
3.1.2 Response Codes
Normal Response Codes: 200
Error Response Codes: 404
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": "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": { } // structure of certificate ommitted for brevity
}
]
"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"]
}
]
},
{
<Liu, et al.> Expires January 3, 2015 [Page 6]
INTERNET DRAFT <Rest for LMAP> July 2, 2014
"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": { } // structure of certificate ommitted for brevity
}
}
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 |
<Liu, et al.> Expires January 3, 2015 [Page 7]
INTERNET DRAFT <Rest for LMAP> July 2, 2014
| 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-
<Liu, et al.> Expires January 3, 2015 [Page 8]
INTERNET DRAFT <Rest for LMAP> July 2, 2014
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:
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
<Liu, et al.> Expires January 3, 2015 [Page 9]
INTERNET DRAFT <Rest for LMAP> July 2, 2014
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 Error Response Codes: 404..
3.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":"",
<Liu, et al.> Expires January 3, 2015 [Page 10]
INTERNET DRAFT <Rest for LMAP> July 2, 2014
"ma-task-options":"",
"ma-task-cycle-id":""
},
{
"ma-task-name":"",
"ma-task-registry":"",
"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":""
},
<Liu, et al.> Expires January 3, 2015 [Page 11]
INTERNET DRAFT <Rest for LMAP> July 2, 2014
"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":""},
...
]
}
}
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
<Liu, et al.> Expires January 3, 2015 [Page 12]
INTERNET DRAFT <Rest for LMAP> July 2, 2014
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 |
+--------------------+-----------+
|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": ""
}
<Liu, et al.> Expires January 3, 2015 [Page 13]
INTERNET DRAFT <Rest for LMAP> July 2, 2014
],
"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": ""
},
{
"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/
<Liu, et al.> Expires January 3, 2015 [Page 14]
INTERNET DRAFT <Rest for LMAP> July 2, 2014
4.2 Response code 200 for success. 404...
4.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": [
<Liu, et al.> Expires January 3, 2015 [Page 15]
INTERNET DRAFT <Rest for LMAP> July 2, 2014
{
"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": ""
}
]
}
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.
<Liu, et al.> Expires January 3, 2015 [Page 16]
INTERNET DRAFT <Rest for LMAP> 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-00 (work in progress), February
2014.
[RFC 2616]
[RFC 4627]
<Liu, et al.> Expires January 3, 2015 [Page 17]
INTERNET DRAFT <Rest for LMAP> July 2, 2014
Authors' Addresses
Dapeng Liu
China Mobile
Email: liudapeng@chinamobile.com
Lingli Deng
China Mobile
Email: denglingli@chinamobile.com
Shu Liu
CATR
Email: liushu@catr.cn
Cathy Li
China Cache
Email: cathy.li@chinacache.com
<Liu, et al.> Expires January 3, 2015 [Page 18]