wdiff draft-ietf-lmap-information-model-00.txt draft-ietf-lmap-information-model-01.txt

Network Working Group T. Burbridge
Internet-Draft P. Eardley
Intended status: Standards Track British Telecom BT
Expires: August 18, December 28, 2014 M. Bagnulo
Universidad Carlos III de Madrid
J. Schoenwaelder
Jacobs University Bremen
February 14,
June 26, 2014

Information Model for Large-Scale Measurement Platforms (LMAP)
draft-ietf-lmap-information-model-00
draft-ietf-lmap-information-model-01

Abstract

This Information Model applies to the Measurement Agent within a
Large-Scale Measurement Platform. As such it outlines the
information that is (pre-)configured on the MA or exists in
communications with a Controller or Collector within an LMAP
framework. The purpose of such an Information Model is to provide a
protocol and device independent view of the MA that can be
implemented via one or more Control and Report protocols.

Requirements Language

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].

Status of this This Memo

This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.

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."

This Internet-Draft will expire on August 18, December 28, 2014.

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
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. Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. LMAP Information Model . . . . . . . . . . . . . . . . . . . . 4
3.1. Information Structure . . . . . . . . . . . . . . . . . . 4
3.2. Pre-Configuration Information . . . . . . . . . . . . . . 5 8
3.3. Configuration Information . . . . . . . . . . . . . . . . 6 9
3.4. Instruction Information . . . . . . . . . . . . . . . . . 7 10
3.5. MA to Controller Logging Information . . . . . . . . . . . . . . . 11 . . . . 13
3.6. Capability and Status Information . . . . . . . . . . . . 13 15
3.7. Reporting Information . . . . . . . . . . . . . . . . . . 14 16
3.8. Schedules . . . . . . . . . . . . . . . . . . . . . . . . 18
3.9. Channels . . . . . . . . . . . . . . . . . . . . . . . . 20
3.10. Task Configurations . 15
3.9. . . . . . . . . . . . . . . . . . . 21
3.11. Timing Information . . . . . . . . . . . . . . . . . . . . 16
3.9.1. 22
3.11.1. Periodic Timing . . . . . . . . . . . . . . . . . . . 17
3.9.2. 23
3.11.2. Calendar Timing . . . . . . . . . . . . . . . . . . . 17
3.9.3. 23
3.11.3. One-Off Timing . . . . . . . . . . . . . . . . . . . . 18
3.9.4. 24
3.11.4. Immediate Timing . . . . . . . . . . . . . . . . . . . 18
3.9.5. 24
3.11.5. Startup Timing Randomness . . . . . . . . . . . . . . . . . . 18 . 25
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 25
5. Security Considerations . . . . . . . . . . . . . . . . . . . 19 25
6. Acknowledgements Appendix: JSON Example . . . . . . . . . . . . . . . . . . . 25
7. Acknowledgements . . . . . 19
7. References . . . . . . . . . . . . . . . . . 34
8. References . . . . . . . . . 20
7.1. . . . . . . . . . . . . . . . . 34
8.1. Normative References . . . . . . . . . . . . . . . . . . . 20
7.2. 34
8.2. Informative References . . . . . . . . . . . . . . . . . . 20 34
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 20 34

1. Introduction

A large-scale measurement platform is a collection of components that
work in a coordinated fashion to perform measurements from a large
number of vantage points. The main components of a large-scale
measurement platform are the Measurement Agents (hereafter MAs), the
Controller(s) and the Collector(s).

The MAs are the elements actually performing the measurements. The
MAs are controlled by exactly one Controller at a time and the
Collectors gather the results generated by the MAs. In a nutshell,
the normal operation of a large-scale measurement platform starts
with the Controller instructing a set of one or more MAs to perform a
set of one or more Measurement Tasks at a certain point in time. The
MAs execute the instructions from a Controller, and once they have
done so, they report the results of the measurements to one or more
Collectors. The overall framework for a Large Measurement platform
as used in this document is described in detail in
[I-D.ietf-lmap-framework].

A large-scale measurement platform involves basically three
protocols, namely, a Control protocol between a Controller and the
MAs, a Report protocol between the MAs and the Collector(s) and
several measurement protocols between the MAs and Measurement Peers
(MPs), used to actually perform the measurements. In addition some
information is required to be provisioned in configured on the MA prior to any
communication with the initial Controller.

This document defines the information model for both the Control and
the Report protocol along with pre-configuration information that is
required before communicating with the Controller, broadly named as
the LMAP Information Model (or LMAP IM for short). Model. The measurement protocols are out of the
scope of this document.

As defined in [RFC3444], the LMAP IM defines the concepts involved in
a large-scale measurement platform at a high level of abstraction,
independent of any specific implementation or actual protocol used to
exchange the information. It is expected that the proposed
information model can be used with different protocols in different
measurement platform architectures and across different types of MA
devices (e.g., home gateway, smartphone, PC, router).

The definition of an Information Model serves a number of purposes:

1. To guide the standardisation of one or more Control and Report
protocol and data model implementations

2. To enable high-level inter-operability between different Control
and Report protocols by facilitating translation between their
respective data models such that a Controller could instruct sub-
populations of MAs using different protocols

3. To from form agreement of what information needs to be held by an MA
and passed over the Control and Report interfaces and support the
functionality described in the LMAP framework

4. Enable existing protocols and data models to be assessed for
their suitability as part of a large-scale measurement system

2. Notation

This document use an adaptation of the C-style struct object-oriented programming-like notation to
define the fields parameters (names/values) of the objects of the
information model. An optional field is enclosed by [ ], and an
array is indicated by two numbers in angle brackets, <m..n>>, where m
indicates the minimal number of values, and n is the maximum. The
symbol * for n means no upper bound.

3. LMAP Information Model

3.1. Information Structure

The information described herein relates to the information stored,
received or transmitted by a Measurement Agent as described within
the LMAP framework [I-D.ietf-lmap-framework]. As such, some subsets
of this information model are applicable to the measurement
Controller, Collector and systems that pre-configure the Measurement
Agent. The information described in these models will be transmitted
across the
by protocols and using interfaces between the Measurement Agent and such
systems according to a Data Model.

For clarity the information model is divided into six sections:

1. Pre-Configuration Information. Information pre-configured on the
Measurement Agent prior to any communication with other
components of the LMAP architecture (i.e., the Controller,
Collector and Measurement Peers), specifically detailing how to
communicate with an initial a Controller and whether the device is enabled
to participate as an MA.

2. Configuration Information. Information delivered to Update of the pre-configuration
information during the MA on registration with a Controller of the MA or updated during a later
communication, in particular detailing how to retrieve
measurement and reporting instruction information from a
Controller subsequent
communication with the Controller, along with information specifically the configuration
of further parameters about the MA. MA (rather than the Tasks it
should perform) that were not mandatory for the initial
communication between the MA and a Controller.

3. Instruction Information. Information that is received by the MA
from the Controller pertaining to the measurement and reporting
configuration. Tasks that should be
executed. This includes measurement configuration, report
channel configuration, measurement schedules the task execution Schedules (other than
the Controller communication Schedule supplied as
(pre)configuration information) and measurement
suppression related information such as
the Task Configuration, communication Channels to Collectors and
schedule Timing information.

4. MA It also inlcudes Task Suppression
information that is used to Controller over-ride normal Task execution
during emergency situations.

4. Logging Information. Information transmitted from the MA to the
Controller detailing the results of any configuration operations
along with error and status information from the operation of the
MA.

5. Capability and Status Information. Information on the general
status and capabilities of the MA. For example, the set of
measurements that are supported on the device.

6. Reporting Information. Information transmitted from the MA to
the Collector including measurement results and the context in
which they were conducted.

In addition the MA may hold further information not described herein,
and which may be optionally transferred to or from other systems
including the Controller and Collector. One example of information
in this category is subscriber or line information that may be
extracted by a task and reported by the MA as optional fields in the reporting
communication to a Collector.

It should also be noted that the MA may be in communication with
other management systems which may be responsible for configuring and
retrieving information from the MA device. Such systems, where
available, can perform an important role in transferring the pre-
configuration information to the MA or enabling/disabling the
measurement functionality of the MA.

The Information Model is divided into sub-sections for a number of
reasons. Firstly the grouping of information facilitates reader
understanding. Secondly, the particular groupings chosen are
expected to map to different protocols or different transmissions
within those protocols.

The granularity of data transmitted in each operation of the Control
and Report Protocols is not dictated by the Information Model. For
example, the Instruction object may be delivered in a single
operation. Alternatively, Schedules and Task Configurations may be
separated or even each Schdule/Task Configuration may be delivered
individually. Similarly the Information Model does not dictate
whether data is read, write, or read/write. For example, some
Control Protocols may have the ability to read back Configuration and
Instruction information which have been previosuly set on the MA.
Lastly, while some protocols may simply overwrite information (for
example refreshing the entire Instruction Information), other
protocols may have the ability to update or delete selected items of
information.

The information in these six sections is captured by a number of
common information objects. These objects are also described later
in this document and comprise of:

1. Schedules. A set of Schedules tell the MA to do something.
Without a Schedule no Task (from a measurement to reporting or
communicating with the Controller) is ever executed. Schedules
are used within the Instruction to specify what tasks should be
performed, when, and how to direct their results. A Schedule is
also used within the pre-Configuration and Configuration
information in order to execute the Task or Tasks required to
communicate with the Controller.

2. Channels. A set of Channel objects are used to communicate with
a number of endpoints (i.e. the Controller and Collectors). Each
Channel object contains the information required for the
communication with a single endpoint such as the target location
and security details. Channels are referenced from within
Schedules in order to say how Tasks should communicate.

3. Task Configurations. A set of Task Configurations is used to
configure the Tasks that are run by the MA. This includes the
registry entry for the Task and any configuration parameters.
Task Configurations are referenced from a Schedule in order to
specify what Tasks the MA should execute.

4. Timings. A set of Timing objects that can be referenced from the
Schedules. Each Schedule always references exactly one Timing
object. A Timing object specfies either a singleton or series of
time events. They are used to indicate when Tasks should be
executed.

The following diagram illustrates the structure in which these common
information objects are referenced. The references are achieved by
each object (Channel, Task Configuration, Timing) being given a short
text name that is used by other objects. The objects shown in
brackets are part of the internal object structure of a Schedule.

It should be clear that the general capability of an MA is simply to
execute Schedules. Every other action of an MA is implemented as a
Task. As such, these actions are configured through Task
Configurations and executed according to the Timing referenced by the
Schedule in which they appear. Tasks can implement a variety of
different types of actions. While in terms of the Information Model,
all Tasks have the same information, it can help conceptually to
think of different Task categories:

1. Measurement Tasks

A. Active Measurement Tasks implement an active measurement
protocol to a remote network host

B. Passive Measurement Tasks analyse traffic passing through the
MA device or traffic that may be eavesdropped

C. Data Capture Tasks capture and analyse passive information
stored on the MA device such as counters and device/network
status information

2. Data Transfer Tasks

A. Reporting Tasks report the results or Measurement Tasks to
Collectors

B. Control Task(s) implement the Control Protocol and
communicate with the Controller. Depending on the Control
Protocol this may be a number of specialist tasks such as:
Configuration Task; Instruction Task; Suppression Task;
Capabilities Task; Logging Task etc.

3. Data Analysis Tasks can exist to analyse data from other
Measurement Tasks locally on the MA

4. Data Management Tasks may exist to clean-up, filter or compress
data on the MA such as Measurement Task results

3.2. Pre-Configuration Information

This information is the minimal information that needs to be pre-
configured to the MA in order for it to successfully communicate with
a Controller during the registration process. The pre-configuration
information is a subset of the Configuration Information along with
some parameters that are not under the control of the LMAP framework
(such as the the device identifier and device security credentials).

This pre-configuration information needs to include a URL of the
initial Controller where configuration information can be retrieved
along with the security information required for the communication
including the certificate of the Controller (or the certificate of
the Certification Authority which was used to issue the certificate
for the Controller) as well as the timing for that communication. Controller). All this is expressed as the Instruction a Channel. As part of Multiple
channels may be given to the
Instruction Channel, Controller (such as over different
interfaces or network protocols).

Where the MA's security MA pulls information from the Controller, the Pre-
Configuration Information also needs to contain the timing of the
communication with the Controller as well as the nature of the
communication itself (such as the protocol and data to be
transfered). The timing is configured given as a Schedule that executes the
Task(s) responsible for communication with the Controller. It is
this Task (or Tasks) that implement the Control protocol between the
MA and the Controller. The Task(s) may take additional parameters in
which case a Task Configuration can also be either included.

Even where information is pushed to the MA from the Controller
(rather than pulled by the MA), a certificate and Schedule still needs to be
supplied. In this case the Schedule will simply execute a private key Controller
listener task when the MA is started. A Channel is still required
for the MA to establish secure communication with the Controller.

It can be seen that these Channels, Schedules and Task Configurations
for the initial MA-Controller communication are no different in terms
of the Information Model to any other Channel, Schedule or Task
Configuration that might execute a password,
depending on Measurement Task or report the security solution used.
measurement results (as described later).

The MA may already be pre-configured with an MA ID, or may use a Device ID in
the initial Controller contact before it is assigned an MA ID. The
Device ID may be a MAC address or some other device identifier
expressed as a URN.

Detail of the information model elements:

// MA pre-configuration minimal information to communicate initially with Controller

object {
[uuid ma-agent-id;]
ma-task-obj ma-control-tasks<0..*>;
ma-channel-obj ma-instruction-channel;
ma-channel-obj ma-ma-to-controller-channel; ma-control-channels<1..*>;
ma-schedule-obj ma-control-schedules<0..*>;
[urn ma-device-id;]
[uuid ma-agent-id;]
credentials ma-credentials;
} ma-preconfig-obj; ma-config-obj;

The detail of the Channel object is and Schedule objects are described later
since it is they are common to several parts of the information model.

3.3. Configuration Information

During registration or at any later point at which the MA contacts
the Controller, Controller (or vice-versa), the choice of Controller and Controller, details for
the timing of communication with the Controller or parameters for the
communication Task(s) can be changed (as captured by the Instruction Channel information object). Channels,
Schedules and Task Configurations objects). For example the pre-
configured Controller (specified as a Channel or Channels) may be
replaced with a specific Controller that is more appropriate to the
MA device type, location or characteristics of the network (e.g.
access technology type or broadband product). The initial
communication timing object Schedule may be replaced with one more relevant to
routine communications between the MA and the Controller.

While some Control protocols and uses may only use a single Schedule,
other protocols and uses may uses several Schedules (and related data
transfer Tasks) to update the Configuration Information, transfer the
Instruction Information, transfer Capability and Status Information
and send other information to the Controller such as log or error
notifications. Multiple Channels may be used to communicate with the
Controller over multiple interfaces (e.g. to send logging information
over a different network).

In addition the MA will be given further items of information that
relate specifically to the MA rather than the measurements it is to
conduct or how to report results. The assignment of an ID to the MA
is mandatory. Optionally a Group ID may also be given which
identifies a group of interest to which that MA belongs. For example
the group could represent an ISP, broadband product, technology,
market classification, geographic region, or a combination of
multiple such characteristics. Where the Measurement Group ID is set
an additional flag (the Report MA ID flag) is required to control
whether the Measurement Agent ID is also to be reported. The
reporting of a Group ID without the MA ID allows the MA to remain
anonymous, which may be particularly useful to prevent tracking of
mobile MA devices.

Optionally an MA can also be configured to stop Measurement Tasks stopexecuting any
Instruction Schedule if the Controller is unreachable. This can be
used as a fail-safe to stop Measurement and other Tasks being
conducted when there is doubt that the Instruction Information is
still valid. This is simply represented as a number of failed time window in
milliseconds since the last communication attempts before Measurement Tasks with the Controller after
which Instruction Schedules are to be suspended. The appropriate number
vaue of failed attempts the time window will depend on the timing of specified communication
Schedule with the Instruction Channel Controller and the duration for which the system is
willing to tolerate continued operation with potentially stale
Instruction Information.

While pre-configuration is persistent upon device reset or power
cycle due to its very nature, the persistency of the addtional
configuration information may be control protocol dependent. Some
protocols may assume that reset devices will revert back to their
pre-configuration state, while other protocols may assume that all
configuration and instruction information is held in persistent
storage.

Detail of the additional and updated information model elements:

// MA Configuration

object {
uuid ma-agent-id;
[ma-task-obj ma-control-tasks<0..*>;]
ma-channel-obj ma-instruction-channel; ma-control-channels<1..*>;
[mas-schedule-obj ma-control-schedules<0..*>];
[urn ma-device-id;]
credentials ma-credentials;
[string ma-group-id;]
[boolean ma-report-ma-id-flag;]
[int ma-instruction-channel-failure-threshold;] ma-control-channel-failure-threshold;]
} ma-config-obj;

3.4. Instruction Information

The Instruction information model has four sub-elements:

1. Measurement Instruction Task Configurations

2. Report Channels

3. Measurement Instruction Schedules
4. Measurement Suppression

Conceptually each Measurement Task Configuration defines

The Instruction supports the
parameters exceution of a Measurement Task all Tasks on the MA except
those that deal with communication with the Measurement Agent (MA) may
perform at some point Controller (specified in time. It does not
(pre)configuration information). The Tasks are configured in
Instruction Task Configurations and inlcuded by itself actually
instruct the MA reference in
Instruction Schdules that specify when to perform them at any particular time (this execute them. The results
are communicated to other Tasks or over Report Channels. Suppression
is done used to temporarily stop the excution of new Tasks as specified by a Measurement Schedule).

Example:
the Instruction Schedules (and optionaly to stop ongoing Tasks).

A Measurement Task Configuration may is used to configure a single
Measurement Task for measuring UDP latency. The Measurement Task
Configuration could define the destination port and address for
the measurement as well as the duration, internal packet timing
strategy and other optional parameters (for example of
a stream for one hour
and sending one packet every 500 ms). Task. It may also define the
output type and possible parameters (for example the output type
can be the 95th percentile mean) where the measurement task
accepts such parameters. It does NOT define when the task starts
(this is defined by the Measurement Schedule element), so it does
not by itself serves to instruct the MA to actually perform this measurement
task.

The Measurement Task Configuration will include a local short name
for reference by about the Measurement Schedule, along with a registry
entry [I-D.bagnulo-ippm-new-registry] that defines Task including
the Measurement
Task. The MA itself will ability to resolve the registry entry Task to a local an executable program. In addition the Measurement Task is specialised
through a set of configuration Options. The nature and number of
these Options will depend upon the Measurement Task and will be
defined in specifying the Measurement Task Registry. In addition
schema for the
Measurement Task Configuration may optionally also be given a
Measurement Cycle ID. The purpose of this ID is parameters.

A Report Channel defines how to easily identify communicate with a
set of measurement results that have been produced single remote
system specified by Measurement
Tasks with comparable Options. This ID is manually incremented when
an Option change is implemented which could mean that two sets of
results should not be directly compared. a URL. A Report Channel defines how is used to report send results
to a single Collector. Collector but is no different in terms of the Information
Model to the Control Channel used to transfer information between the
MA and the Controller. Several Report Channels can be defined to
enable results to be split or duplicated across different report intervals or
destinations. A single Channel can also be used by multiple
Schedules to transfer data at different cycles to the same Collector.
E.g. a single Collector may have receive data at three Report Channels, different cycle
rates, one Schedule reporting hourly, another reporting daily and a
third on which to send
immediate specifying that results should be sent immediately for on-demand on-
demand measurement tasks. Alternatively multiple Report Channels can
be used to send Measurement Task results to different Collectors.
The details of the Channel element is described later as it is common
to several objects.

A Measurement Schedule contains the

Instruction from the Controller Schedules specify which Tasks to the MA execute according to a
simngle given Timing (that can execute a single or repeated series of Measurement
Tasks. Each Measurement Schedule contains basically two elements: a
reference to a list of Measurement Task Configuration and a timing
object for the schedule.
Tasks). The schedule basically states what
measurement task to run, Schedule also specifies how to report the results per Measurement deal with Task Configuration, inputs and when to run the measurement task. Multiple
measurement tasks in the list will be executed in order with minimal
gaps. Note that the Controller can instruct the MA to report
outputs - e.g. sending selected outputs to
several Collectors by other Tasks or specifying several Report Channels.

Each Measurement Task Configuration named in
the Measurement Schedule
can be allocated to independent Report Channels, giving flexibility
to report different Measurement Tasks to different Collectors or on
different timings. Furthermore, as each Measurement Task may have
multiple data outputs, these outputs can each Channels that should be assigned used to
different Report Channels. For example a Measurement Task might report routine results hourly via the Broadband PPP interface, but
also output emergency conditions immediately via a GPRS channel.

Example: a Measurement Schedule references a single Measurement Task
Configuration for the UDP latency defined in the previous example.
It references the Report Channel in the previous example to send
results immediately as available to the specified Collector. The
timing is specified to run the configured Measurement Task
Configuration every hour at 23 minutes past the hour.
Collectors.

Measurement Suppression information is used to over-ride the
Measurement
Instruction Schedule and temporarily stop measurements or other Tasks
from running on the MA for a defined or indefinite period. While
conceptually measurements can be stopped by simply removing them from
the Measurement Schedule, splitting out separate information on
Measurement Suppression allows this information to be updated on the
MA on a different timing cycle or protocol implementation to the
Measurement Schedule. It is also considered that it will be easier
for a human operator to implement a temporary explicit suppression
rather than having to move to a reduced Schedule and then roll-back
at a later time.

The explicit Suppression instruction message is able to simply
enable/disable all
Measurement Instruction Tasks (that are enabled for default
suppression) as well as having fine control on which Tasks are
suppressed. Suppression of both specified Measurement Tasks Task Configurations and
Measurement Schedules is supported. Support for disabling specific Measurement
Task Configurations allows malfunctioning or mis-configured Measurement Tasks or Measurement
Task Configurations that have an impact on a particular part of the
network infrastructure (e.g., a particular Measurement Peer) to be
targetted. Support for disabling specific Measurement Schedules allows for
particularly heavy cycles or sets of less essential Measurement Tasks
to be suppressed quickly and effectively. Note that Suppression has
no effect on either Controller Tasks or Controller Schedules.

When no tasks or schedules are explicitly listed, all Instruction
tasks will be suppressed as indicated by the suppress-by-default flag
in the Task Configuration. If tasks or schedules are listed
explicitly then these tasks will be suppressed regardless of the
suppress-by-default flag.

Suppression stops new Tasks from executing. In addtion, the
Suppression information also supports an additional Boolean that is
used to select whether on-going tasks are also to be terminated.

Unsuppression is achieved through either overwriting the Measurement
Suppression information (e.g. changing 'enabled' to False) or through
the use of an End time such that the Measurement Suppression will no
longer be in effect beyond this time. The datetime format used for
all elements in the information model (e.g. the suppression start and
end dates) MUST conform to RFC 3339 [RFC3339] and ISO8601.

The goal when defining these four different elements is to allow each
part of the information model to change without affecting the other
three elements. For example it is envisaged that the Report Channels
and the set of Measurement Tasks Task Configurations will be relatively static. The Measurement Schedule
Instruction Schedule, on the other hand hand, is likely to be more dynamic
dynamic, as the measurement panel and test frequency are changed for
various business goals. Another example is that measurements can be
suppressed with a Measurement Suppression command without removing the existing Measurement
Instruction Schedules that would continue to apply after the Measurement
Suppression expires or is removed. In terms of the Controller-MA
communication this can reduce the data overhead. It also encourages
the re-use of the same standard Measurement Task Configurations and Reporting
Channels to help ensure consistency and reduce errors.

Definition of the information model elements:

// Instruction to the MA to configure Tasks, Channels, Schedules and Suppression

object {
ma-task-obj ma-tasks<0..*>; ma-instruction-tasks<0..*>;
ma-channel-obj ma-report-channels<0..*>;
ma-schedule-obj ma-schedules<0..*>; ma-instruction-schedules<0..*>;
ma-suppression-obj ma-suppression;
} ma-instruction-obj;

object {
string ma-task-name;
urn ma-task-registry;
string ma-task-options<0..*>;
[string ma-task-cycle-id;]
} ma-task-obj;

object {
string ma-schedule-name;
ma-sched-task-obj ma-schedule-tasks<0..*>;
ma-timing-obj ma-schedule-timing;
} ma-schedule-obj;

object {
string ma-schedule-task-name;
ma-sched-report-obj ma-schedule-task-reports<0..*>;
} ma-sched-task-obj;

object {
[int ma-schedule-task-filter;]

// default: all
string ma-schedule-task-report-channel-name;
} ma-sched-report-obj; Suppression object to temporarily override new task execution in Instructions and optionally stop currently running tasks

object {
boolean ma-suppression-enabled;
[boolean ma-suppression-stop-ongoing-tasks;] // default: false
[datetime ma-suppression-start;] // default: immediate
[datetime ma-suppression-end;] // default: indefinite
[string ma-suppression-task-names<0..*>;]
// default: all tasks if
// ma-suppression-task-names is empty
[string ma-suppression-schedule-names<0..*>;]
// default: all schedules if
// ma-suppression-schedule-names is empty
} ma-suppression-obj;

3.5. MA to Controller Logging Information

The MA may report on the success or failure of Configuration or
Instruction communications from the Controller. In addition further
operational logs may be produced during the operation of the MA and
updates to capabilities may also be reported. Reporting this
information is achieved simply and flexibly in exactly the same
manner as any Measurement other Task. We make no distinction between a
Measurement Task conducting an active or passive network measurement
and one which solely retrieves static or dynamic information from the
MA such as capabilities or logging information. One or more logging
tasks can be programmed or configured to capture subsets of the MA to Controller
Logging Information. These logging tasks are then executed by Measurement
Schedules (if
not permanently running) and which also specify that the resultant data assigned is to be
transferred over the MA to Controller Channel. Channels.

The type of MA to Controller Logging Information will fall into three different
categories:

1. Success/failure/warning messages in response to information
updates from the Controller. Failure messages could be produced
due to some inability to receive or parse the Controller
communication, or if the MA is not able to act as instructed.
For example:

* "Measurement Schedules updated OK"

* "Unable to parse JSON"

* "Missing mandatory element: Measurement Timing"

* "'Start' does not conform to schema - expected datetime"

* "Date specified is in the past"

* "'Hour' must be in the range 1..24"

* "Schedule A refers to non-existent Measurement Task
Configuration"

* "Measurement Task Configuration X registry entry Y not found"

* "Updated Measurement Task Configurations do not include M used
by Measurement Schedule N"

2. Operational updates from the MA. For example:

* "Out of memory: cannot record result"

* "Collector 'collector.example.com' not responding"

* "Unexpected restart"

* "Suppression timeout"

* "Failed to execute Measurement Task Configuration H"

3. Status updates from the MA. For example:

* "Interface added: eth3 "

* "Supported measurements updated"

* "New IP address on eth0: xxx.xxx.xxx.xxx"

This Information Model document does not detail the precise format of
logging information since it is to a large extend extent protocol and
measurement task MA
specific. However, some common information can be identified.

MA Logging information model elements:

// Logging object

object {
uuid ma-log-agent-id;
datetime ma-log-event-time;
code ma-log-code;
string ma-log-description;
} ma-log-obj;

3.6. Capability and Status Information

The MA will hold Capability Information that can be retrieved by a
Controller. Capabilities include the interface details available to
Measurement Tasks and Reports Channels as well as the set of Measurement
Tasks that are actually installed or available on the MA. Status
information includes the times that operations were last performed
such as contacting the Controller or producing Reports.

MA Status information model elements:

// Main MA Status information object

object {
uuid ma-agent-id;
urn ma-device-id;
string ma-hardware;
string ma-firmware;
string ma-software; ma-version;
ma-interface-obj ma-interfaces<0..*>;

datetime ma-last-measurement;
datetime ma-last-report;
datetime ma-last-instruction;
datetime ma-last-configuration;

ma-capability-obj ma-supported-measurements<0..*>;

ma-task-capability-obj ma-supported-tasks<0..*>;
} ma-status-obj;
// Interface information

object {
string ma-interface-name;
string ma-interface-type;
int ma-interface-speed;
[int ma-interface-speed;] // mbps
string ma-link-layer-address;
ip-address ma-interface-ip-addresses<0..*>;
[string ma-link-layer-address;]
[ip-address ma-interface-ip-addresses<0..*>];
[ip-address ma-interface-gateways<0..*>;]
[ip-address ma-interface-dns-servers<0..*>;]
} ma-interface-obj;

// Supported tasks

object {
urn ma-measurement-id;
[string ma-measurement-version;]
string ma-task-name;
uri ma-task-registry;
} ma-capability-obj; ma-task-capability-obj;

3.7. Reporting Information

At a point in time specific specified by the Report Channel, a Schedule, the MA will execute a
task or tasks that communicate a set of measurement results to the
Collector. These
measurement Some of these Tasks (notably Reporting Tasks) will
understand how to transmit task results should be communicated within the context in
which they were collected. over a specified Report
Channel to a Collector.

It should be noted that Collectors can be implemented by many types
of devices and systems, including the MA itself. In this manner data output from Measurement Tasks does not need to be
sent to communication Channels. It can (also) alternatively, or
additionally, be stored locally sent to other Tasks on the MA and
used as input by other Measurement Tasks. MA. This facilitates
using a first Measurement Task to control the operation of a later
Measurement Task (such as first probing available line speed) speed and then
adjusting the operation of a video testing measurement) and also to
allow local processing of data to output alarms (e.g. when
performance drops from earlier levels). Of course, subsequent Tasks
also include Tasks that implement the reporting protocol(s) and
transfer data to one or more Collector(s).

The report is structured hierarchically to avoid repetition of
report, Measurement Agent report
header and Measurement Task Configuration information. The report
starts with the timestamp of the report generation on the MA and
details about the MA including the optional Measurement Agent ID and
Group ID (controlled by the Configuration Information). In addition optional further MA

No context information
can be included at this point information, such as the line sync speed or ISP and broadband product if known are
included within the report header information as this data is
reported by individual tasks at the MA. time they execute. Either a
Measurement Task can report contextual parameters that are relevant
to that particular measurement, or specific tasks can be used to
gather a set of contextual and environmental data. at certain times
independent of the reporting schedule.

After the MA report header information the results are reported grouped into the
according to different Measurement Tasks. Task Configurations. Each Measurement Task
section starts with replicating the Measurement Task Configuration
information before the result headers (titles for data columns) and
the result data rows. The result data rows may optionally include an
indication of the
cross-traffic (e.g., cross-traffic. Cross traffic is defined as the
total number of octets Bytes both upstream and downstream of non-measurement
traffic passing through the interfaces used by a Measurement Task
during the measurement period).

The datetime format used for all elements in period.

Where the Configuration and Instruction information model
(i.e., represent
information transmitted via the Control Protocol, the Report
represents the information that is transmitted via the Report Date
Protocol. It is constructed at the time of sending a report and Measurement Time in
represents the Reporting Information)
MUST conform inherent structure of the information that is sent to RFC 3339 [RFC3339] and ISO8601.
the Collector.

Information model elements:

// Main Report object with report header information

object {
datetime ma-report-date;
[uuid ma-report-agent-id;]
[string ma-report-group-id;]
ma-context-obj ma-report-context<0..*>;
ma-report-task-obj ma-report-tasks<0..*>;
} ma-report-obj;

// Report task header information

object {
ma-task-obj ma-report-task-config;
string ma-report-task-column-headers<0..*>; ma-report-task-column-labels<0..*>;
ma-result-row-obj ma-report-task-rows<0..*>;
} ma-report-task-obj;

// Report tasks result rows

object {
datetime ma-report-result-time;
string ma-report-conflicting-tasks<0..*>;
[int ma-report-result-cross-traffic;] // Bytes of non-measurement traffic
// on measurement interface during measurement period
data ma-report-result-values<0..*>;
} ma-result-row-obj;

The ma-context-obj, which covers things like line speed or the device
type, is not further detailed here.

3.8. Channels Schedules

A Channel defines Schedule specifies the execution of a communication channel between single or repeated series of
Tasks. Each Schedule contains basically two elements: a list of
Tasks to be executed and a timing object for the MA Schedule. The
Schedule basically states what Tasks to run (with what
configuration), how to report the results, and other
element of when to run the measurement framework i.e. Tasks.

Multiple Tasks in the list of a single Measurement Schedule will be
executed in order with minimal gaps. Tasks in different Schedules
can execute in parallel with such conflicts beings reported in the Collector
Reporting Information.

As well as specifying which Tasks to execute, the Schedule also
specifies where to send the data outputs from each Task. Specifying
this within the Schedule allows the highest level of flexibility
since it is even possible to send the output from different
executions of the same Task to different destinations. Since a
single Task may have multiple outputs, the Schedule can independently
specify which outputs go to which destinations. For example, a
Measurement Task might report routine results back, to Controller a data Reporting
Task that communicates hourly via the Broadband PPP interface, but
also outputs emergency conditions via an alarm Reporting Task
communicating immediately over a GPRS channel.

The destination options for a Task are either another Task or a
Channel. In this way the output of a Task can be sent to retrieve Instructions another
Task. For example a Measurement Task may send its output to a data
transfer Task that reports the batched data to a Collector at a later
time. Alternatively the output from a Measurement Task may be fed to
an alarm processing task that monitors the results of a series of
Measurement Tasks. Some Tasks will also understand how to send/
receive data to/from Channels using the Reporting/Control protocol.
Since Channels are bi-directional they can be considered inputs as
well as outputs to the Control and Reporting Tasks that utlilise
them. Any Task that does not implement either the Reporting or
Control protocol will ignore any specified Channels (e.g. A
Measurement Task will not know how to report results to a Collector
using the Report Protocol. Instead results can be passed to a
Reporting Task that has the apropriate Collector specified as a
Channel).

The tasks outputs and channels are controlled using a series of
filters. Each filter is an array of integers specifying which Task
datasets should be mapped to which output tasks and/or channels.

Example: A Schedule references a single Measurement Task
Configuration for the UDP latency. It specifies that results are
to be sent to a Reporting Task. This Reporting Task is executed
by a separate Schedule that specifies that it should run hourly at
5 minutes past the hour. When run this Reporting Task takes the
data generated by the UDP latency Task as well as any other
information exchanged data
to be included in the hourly report and transfers it to the
Collector over the Report Channel specified within its own
Schedule.

// main Schedule object with Timing and list of Scheduled Tasks

object {
string ma-schedule-name;
ma-sched-task-obj ma-schedule-tasks<0..*>;
ma-timing-obj ma-schedule-timing;
} ma-schedule-obj;

// Scheduled Task object with reference (by name string) to Task Configuration and input/output mapping
// of task datasets to output tasks and channels

object {
string ma-schedule-task-name;
ma-sched-dataset-obj ma-schedule-task-datasets<0..*>;
} ma-sched-task-obj;

// Selected Task interfaces (filtered by Integer list) can be output to other Task Configurations
// (referenced by name string) or connected to input/output Channels (referenced by name string)

object {
[int ma-schedule-task-filters<0..*>;] // default: all
[string ma-schedule-task-output-task-names<0..*>];
[string ma-schedule-task-channel-names<0..*>];
} ma-sched-dataset-obj;
3.9. Channels

A Channel defines a bi-directional communication channel between the parties. Several
MA and a Controller or Collector. Multiple Channels can be defined
to enable results to be split or duplicated across different
report intervals or destinations. E.g. a single Collector may have
three Report Channels, one reporting hourly, another reporting daily
and a third on which to send immediate results for on-demand
measurement tasks.
Collectors.

Each Channel contains the details of the target endpoint (including location
and security credential information such as the certificate), and the certificate). The
timing for
the communication i.e. of when to establish communicate over a Channel is specified within the communication.
Schedule. The certificate can be the digital certificate associated
to the FQDN in the URL or it can be the certificate of the
Certification Authority that was used to issue the certificate for
the FQDN (Fully Qualified Domain Name) of the target URL (which will
be retrieved later on using a communication protocol such as SSL). The Channel can TLS).
In order to establish a secure channel, the MA will use it's own
security credentials (in the
same timing information object as a Measurement Schedule Configuration Information) and the
Controller Communication Timing defined earlier. There are several
options, such as immediately after the results are obtained or at a given interval or calendar based cycle).
credentials for the individual Channel end-point.

As with the Measurement
task Configuration, theTask Configurations, each Channel is also given a local
short name by which it can be referenced from a Measurement Schedule or other
elements.

As Schedule.

Although the same in terms of information, Channels used for Measurement Tasks, multiple
communication with the Controller are refered to as Control Channels
whereas Channels to Collectors are refered to as Report Channels.
Hence Control Channels will be referenced from within the Control
Schedule, whereas Report Channels will be referenced from within the
Instruction Schedule.

Multiple interfaces are also supported. For example the Controller
could choose to receive some results over GPRS. This is especially
useful when such results indicate the loss of connectivity on a
different network interface.

Facility is also provided for the Controller to choose whether to
receive empty reports where there is no Measurement Task information.
In some cases this may be desirable to monitor the health of the
measurement system.

Example: A Channel using for reporting results may specify that
results are to be sent to the URL
(https://collector.foo.org/report/), (https://collector.foo.org/
report/), using the appropriate digital certificate to establish a
secure channel. The channel..

// Channel specifies
that the results are object with name string allowing reference from Schedule. Contains channel endpoint target URL and security
// credentials to be sent immediately as available establish secure channel. Optionally allows interface specification (by interface name string reference)
// and not
batched. connection when no data is pending for transfer

object {
string ma-channel-name;
url ma-channel-target;
certificate ma-channel-certificate;
ma-timing-obj ma-channel-timing;
credentials ma-channel-credentials;
[string ma-channel-interface-name;]
[boolean ma-channel-connect-always;]
// default: false
// (only connect
} ma-channel-obj;

3.10. Task Configurations

Conceptually each Task Configuration defines the parameters of a Task
that the Measurement Agent (MA) may perform at some point in time.
It does not by itself actually instruct the MA to perform them at any
particular time (this is done by a Schedule). Tasks can be
Measurement Tasks (i.e. those Tasks actually performing some type of
passive or active measurement) or any other scheduled activity
performed by the MA such as transferring information to or from the
Controller and Collectors. Other examples of Tasks may include data
manipulation or processing Tasks conducted on the MA.

A Measurement Task Configuration is the same in information terms to
any other Task Configuration. Both measurement and non-measurement
Tasks have a registry entry to enable the MA to uniquely identify the
Task it should execute and retrieve the schema for any parameters
that may be passed to the Task. This registry entry is specified as
a URI and can therefore identify the Task within a namespace or point
to a web or local file location for the Task information. As
mentioned previously this entry may refer to the Measurement Task in
a public namespace [I-D.bagnulo-ippm-new-registry] that is used to
define the Measurement Task.

Example: A Measurement Task Configuration may configure a single
Measurement Task for measuring UDP latency. The Measurement Task
Configuration could define the destination port and address for
the measurement as well as the duration, internal packet timing
strategy and other parameters (for example a stream for one hour
and sending one packet every 500 ms). It may also define the
output type and possible parameters (for example the output type
can be the 95th percentile mean) where the measurement task
accepts such parameters. It does NOT define when the task starts
(this is defined by the Schedule element), so it does not by
itself instruct the MA to actually perform this Measurement Task.

The Task Configuration will include a local short name for reference
by a Schedule. Task Configurations will also contain a registry
entry as described above. In addition the Task can be configured
through a set of configuration Options. The nature and number of
these Options will depend upon the Task and will be resolved through
the registry parameter.

A parameter that may be present for Reporting Tasks is whether to
report if there is no measurement result data pending to be
transferred to the Collector.

The Task Configuration also contains a suppress-by-default flag that
specifies the behaviour of a default suppress instruction (that does
not list explicit tasks or schedules). If this flag is set to FALSE
then the Task will not be suppressed. It should be noted that
Controller Tasks are not subject to the suppression instruction and
therefore this flag will be ignored in such cases.

In addition the Task Configuration may optionally also be given a
Measurement Cycle ID. The purpose of this ID is to easily identify a
set of measurement results that have been produced by Measurement
Tasks with comparable Options. This ID could be manually incremented
or otherwise changed when an Option change is pending) implemented which could
mean that two sets of results should not be directly compared.

// Task Configuration object with string name to allow reference from Schedule. Contains URI to link to registry or local
// specification of Task. Options allow the configuration of Task parameters (in the form of name-value pairs)

object {
string ma-task-name;
uri ma-task-registry;
name-value-pair ma-task-options<0..*>;
[boolean ma-task-suppress-by-default;] // default: TRUE
[string ma-task-cycle-id;]
} ma-channel-obj;

3.9. ma-task-obj;

3.11. Timing Information

The Timing information object used throughout the information models
can take one of four five different forms:

1. Periodic. Specifies a start, end and interval time in
milliseconds

2. Calendar: Specifies a calendar based pattern - e.g. 22 minutes
past each hour of the day on weekdays

3. One Off: A single instance occurring at a specific time

4. Immediate: Should occur as soon as possible
5. Startup: Should occur whenever the MA is started (e.g. at device
startup)

Optionally each of the first three options may also specify a randomness that
should be evaluated and applied separately to each indicated event.

The datetime format used for all elements in the information model
(i.e., Report Date and Measurement Time in the Reporting Information)
MUST conform to RFC 3339 [RFC3339] and ISO8601.

// Main Timing object with name string to allow reference by Schedule
// Must be specialised by one of the Timing options.
// Includes optional uniform random spread in ms from start time given by Timing specialisation

object {
[string ma-timing-name;]
union {
ma-periodic-obj ma-timing-periodic;
ma-calendar-obj ma-timing-calendar;
ma-one-off-obj ma-timing-one-off;
ma-immediate-obj ma-timing-immediate;
ma-startup-obj ma-timing-startup;
}
[ma-randomness-obj ma-timing-randomness;]
[int ma-timing-random-spread;] // milliseconds
} ma-timing-obj;

3.9.1.

3.11.1. Periodic Timing

Information model elements:

// Timing specialisation to run a series of Tasks repeated at set intervals

object {
[datetime ma-periodic start;] // default: immediate
[datetime ma-periodic-end;] // default: indefinite
int ma-periodic-interval; // milliseconds
} ma-periodic-obj;

3.9.2.

3.11.2. Calendar Timing

Calendar Timing supports the routine execution of Measurement Tasks
at specific times and/or on specific dates. It can support more
flexible timing than Periodic Timing since the Measurement Task
execution does not have to be uniformly spaced. For example a
Calendar Timing could support the execution of a Measurement Task
every hour between 6pm and midnight on weekdays only.

Calendar Timing is also required to perform measurements at
meaningful instances in relation to network usage (e.g., at peak
times). If the optional timezone offset is not supplied then local
system time is assumed. This is essential in some use cases to
ensure consistent peak-time measurements as well as supporting MA
devices that may be in an unknown timezone or roam between different
timezones (but know their own timezone information such as through
the mobile network).

Information model elements:

// Timing specialisation to run repeated Tasks at specific times and/or days

object {
[datetime ma-calendar-start;] // default: immediate
[datetime ma-calendar-end;] // default: indefinite
[int ma-calendar-months<0..*>;] // default: 1-12
[days ma-calendar-weekdays<0..*>;] ma-calendar-days-of-week<0..*>;] // default: all
[int ma-calendar-hours<0..*>;] // default: 0-23
[int ma-calendar-minutes<0..*>;] // default: 0-59
[int ma-calendar-seconds<0..*>;] // default: 0-59
[int ma-calendar-timezone-offset;]
// default: system timezone offset
} ma-calendar-obj;

3.9.3.

3.11.3. One-Off Timing

Information model elements:

// Timing specialisation to run once at a specified time/date

object {
datetime ma-one-off-time;
} ma-one-off-obj;

3.9.4.

3.11.4. Immediate Timing

The immediate timing object has no further information elements. The
measurement or report is simply to be done as soon as possible.

// Timing specialisation to run immediately

object {
// empty
} ma-immediate-obj;

3.9.5.

3.11.5. Startup Timing Randomness

The Timing randomness immediate timing object specifies a random distribution that can
be applied to any scheduled execution event such as a has no further information elements. The
measurement or
report. The intention it to be able to spread the load on the
Controller, Collector and network in an automated manner for a large
number of Measurement Agents. The randomness report is expressed as a
distribution (e.g. Poison, Normal, Uniform etc.) along with the
spread over which the distribution should be applied. In additional
optional upper and lower bounds can be applied simply done at MA initiation.

// Timing specialisation to control extreme
spread of timings.

Information model elements: run at MA startup

object {
string ma-randomness-distribution;
[int ma-randomness-lower-cut;]
[int ma-randomness-upper-cut;]
int ma-randomness-spread;
// empty
} ma-randomness-obj; ma-startup-obj;

4. IANA Considerations

This document makes no request of IANA.

Note to RFC Editor: this section may be removed on publication as an
RFC.

5. Security Considerations

This Information Model deals with information about the control and
reporting of the Measurement Agent. There are broadly two security
considerations for such an Information Model. Firstly the
Information Model has to be sufficient to establish secure
communication channels to the Controller and Collector such that
other information can be sent and received securely. Additionally,
any mechanisms that the Network Operator or other device
administrator employs to pre-configure the MA must also be secure to
protect unauthorized parties from modifying pre-configuration
information. The second consideration is that no mandated
information items should pose a risk to confidentiality or privacy
given such secure communication channels. For this latter reason
items such as the MA context and MA ID are left optional and can be
excluded from some deployments. This would, for example, allow the
MA to remain anonymous and for information about location or other
context that might be used to identify or track the MA to be omitted
or blurred.

6. Appendix: JSON Example

In order to give an example of data in the Information Model we need
to select a data model language. In this example we have expressed
the Data Model using JSON as this will be of direct interest to some
Control and Report Protocols. The example is broken down into a
number of different steps that might adhere to the steps within a
Control and Report Protocol:

1. Pre-configuration.

2. Configuration

3. Capabilities

4. Instruction

5. Report

6. Suppression

While the pre-configuration is not delivered as part of the Control
Protocol, the same JSON data model is used for consistency and to aid
the reader.

// Pre-Configuration

{
"ma-config": {
"ma-agent-id": "550e8400-e29b-41d4-a716-446655440000",
"ma-control-tasks": [
{
"ma-task-name": "Controller configuration",
"uri": "urn:ietf:lmap:control:http_controller_configuration"
}
]
"ma-control-channels": [
{
"ma-channel-name": "Controller channel",
"ma-channel-target": "http://www.example.com/lmap/controller",
"ma-channel-credientials": { } // structure of certificate ommitted for brevity
}
]
"ma-control-schedules": [
{
"ma-schedule-name": "pre-configured schedule",
"ma-schedule-tasks": {
{
"ma-schedule-task-name": "Controller configuration",
"ma-schedule-task-datasets": [
{
"ma-schedule-task-channel-names": "Controller channel"
}
]
}
}
"ma-schedule-timing": {
"ma-timing-name": "startup plus up to one hour",
"ma-timing-startup": {
}
"ma-timing-random-spread": "3600000"
}
}
]
"ma-credentials": { } // structure of certificate ommitted for brevity
}
}

Given the pre-configuration information the MA is able to contact the
Controller and receive an updated/expanded Configuration. In this
example additional Control Protocol tasks to post Status and
Capabilities to the Controller and fetch the Instruction are added as
well as moving the schedule timing for contacting the Controller to
hourly.

// Configuration

{
"ma-config": {
"ma-agent-id": "550e8400-e29b-41d4-a716-446655440000",
"ma-control-tasks": [
{
"ma-task-name": "Controller configuration",
"uri": "urn:ietf:lmap:control:http_controller_configuration"
},
{
"ma-task-name": "Controller status and capabilities",
"uri": "urn:ietf:lmap:control:http_controller_status_and_capabilities"
},
{
"ma-task-name": "Controller instruction",
"uri": "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-task-datasets": [
{
"ma-schedule-task-channel-names": ["Controller channel"]
}
]
},
{
"ma-schedule-task-name": "Controller status and capabilities",
"ma-schedule-task-datasets": [
{
"ma-schedule-task-channel-names": ["Controller channel"]
}

]
},
{
"ma-schedule-task-name": "Controller instruction",
"ma-schedule-task-datasets": [
{
"ma-schedule-task-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
}
}

The above configuration now contacts the Controller randomnly within
each hour. The following is an example of the Status and
Capabilities information that is transferred from the MA to the
Controller.

// Status and Capabilities

{
ma-status-and-capabilities {
"ma-agent-id": "550e8400-e29b-41d4-a716-446655440000",
"ma-device-id": "urn:dev:mac:0024befffe804ff1"
"ma-hardware": "mfr-home-gateway-v10"
"ma-firmware": "25637748-rev2a"
"ma-version": "ispa-v1.01"
"ma-interfaces: [
{
"ma-interface-name": "broadband",
"ma-interface-type": "PPPoE"
}
]
"ma-last-measurement: "",
"ma-last-report: "",
"ma-last-instruction: "",
"ma-last-configuration: "2014-06-08T22:47:31+00:00",
"ma-supported-tasks: [
{
"ma-task-name": "Controller configuration",
"ma-task-registry": "urn:ietf:lmap:control:http_controller_configuration"
},
{
"ma-task-name": "Controller status and capabilities",
"ma-task-registry": "urn:ietf:lmap:control:http_controller_status_and_capabilities"
},
{
"ma-task-name": "Controller instruction",
"ma-task-registry": "urn:ietf:lmap:control:http_controller_instruction"
},
{
"ma-task-name": "Report",
"ma-task-registry": "urn:ietf:lmap:report:http_report"
},
{
"ma-task-name": "UDP Latency",
"ma-task-registry": "urn:ietf:ippm:measurement:UDPLatency-Poisson-XthPercentileMean"
}
]
}
}
After fetching the status and capabilties the Controller issues and
Instruction to the MA to perform a single UDP latency measurement
task 4 times a day and to report the results immediately.

// Instruction

{
"ma-instruction": {
"ma-instruction-tasks": [
{
"ma-task-name": "UDP Latency",
"uri": "urn:ietf:ippm:measurement:UDPLatency-Poisson-XthPercentileMean",
"ma-task-options": [
{"name": "X", "value": "99"},
{"name":"rate", "value": "5"},
{"name":"duration", "value": "30.000"},
{"name":"interface", "value": "broadband"},
{"name":"destination-ip", "value": {"version":"ipv4", "ip-address":"192.168.2.54"}},
{"name":"destination-port", "value": "50000"},
{"name":"source-port", "value": "50000"}
],
"ma-task-suppress-by-default": "TRUE"
},
{
"ma-task-name": "Report",
"uri": "urn:ietf:lmap:report:http_report",
"ma-task-options": [
{"name": "report-with-no-data", "value": "FALSE"}
],
"ma-task-suppress-by-default": "FALSE"
}
]
"ma-report-channels": [
{
"ma-channel-name": "Collector A",
"ma-channel-target": "http://www.example2.com/lmap/collector",
"ma-channel-credientials": { } // structure of certificate ommitted for brevity
}
]
"ma-instruction-schedules": [
{
"ma-schedule-name": "4 times daily test UDP latency and report",
"ma-schedule-tasks": {
{
"ma-schedule-task-name": "UDP Latency",
"ma-schedule-task-datasets": [
{
"ma-schedule-task-output-task-names": "Report"

}
]
},
{
"ma-schedule-task-name": "Report",
"ma-schedule-task-datasets": [
{
"ma-schedule-task-channel-names": "Collector A"
}
]
}
}
"ma-schedule-timing": {
"ma-timing-name": "once every 6 hours",
"ma-timing-calendar": {
"ma-calendar-hours": ["00", "06", "12", "18"],
"ma-calendar-minutes": ["00"],
"ma-calendar-seconds": ["00"]
}
"ma-timing-random-spread": "21600000"
}
}
]
}
}

The report task in the Instruction is executed immediately after the
UDP test and transfers the following data to the Collector.

// Report

{
ma-report: {
"ma-report-date": "2014-06-09T02:30:45+00:00",
"ma-report-agent-id": "550e8400-e29b-41d4-a716-446655440000",
"ma-report-tasks": [
"ma-report-task-config": {
"ma-task-name": "UDP Latency",
"uri": "urn:ietf:ippm:measurement:UDPLatency-Poisson-XthPercentileMean",
"ma-task-options": [
{"name": "X", "value": "99"},
{"name":"rate", "value": "5"},
{"name":"duration", "value": "30.000"},
{"name":"interface", "value": "broadband"},
{"name":"destination-ip", "value": {"version":"ipv4", "ip-address":"192.168.2.54"}},
{"name":"destination-port", "value": "50000"},
{"name":"source-port", "value": "50000"}
]
},
"ma-report-task-column-labels": ["time", "conflicting-tasks", "cross-traffic", "mean"],
"ma-report-task-rows": [
{"2014-06-09T02:30:10+00:00", "", "0", "20.13"}
]
]
}
}

The Controller decides that there is a problem with the UDP L:atency
test and issues a Suppression Instruction. Since the task is marked
as suppressable by default, simply turning on suppression will stop
the task being executed in future.

// Suppression

{
"ma-instruction": {
"ma-suppression": {
"ma-suppression-enabled": "TRUE"
{
}
}

7. Acknowledgements

The notation was inspired by the notation used in the ALTO protocol
specification.

Philip Eardley, Trevor Burbridge, Marcelo Bagnulo and Juergen
Schoenwaelder work in part on the Leone research project, which
receives funding from the European Union Seventh Framework Programme
[FP7/2007-2013] under grant agreement number 317647.

8. References
7.1.

8.1. Normative References

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.

[RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the
Internet: Timestamps", RFC 3339, July 2002.

7.2.

8.2. Informative References

[I-D.bagnulo-ippm-new-registry]
Bagnulo, M., Burbridge, T., Crawford, S., Eardley, P., and
A. Morton, "A registry for commonly used metrics",
draft-bagnulo-ippm-new-registry-01 draft-
bagnulo-ippm-new-registry-01 (work in progress), July
2013.

[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-03 draft-ietf-lmap-
framework-03 (work in progress), January 2014.

[RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between
Information Models and Data Models", RFC 3444, January
2003.

Authors' Addresses

Trevor Burbridge
British Telecom
BT
Adastral Park, Martlesham Heath
Ipswich,
Ipswich IP5 3RE
United Kingdom

Email: trevor.burbridge@bt.com
Philip Eardley
British Telecom
BT
Adastral Park, Martlesham Heath
Ipswich,
Ipswich IP5 3RE
United Kingdom

Email: philip.eardley@bt.com

Marcelo Bagnulo
Universidad Carlos III de Madrid
Av. Universidad 30
Leganes, Madrid, Madrid 28911
Spain

Email: marcelo@it.uc3m.es

Juergen Schoenwaelder
Jacobs University Bremen
Campus Ring 1
Bremen,
Bremen 28759
Germany

Email: j.schoenwaelder@jacobs-university.de