draft-ietf-lmap-information-model-02.txt   draft-ietf-lmap-information-model-03.txt 
Network Working Group T. Burbridge Network Working Group T. Burbridge
Internet-Draft P. Eardley Internet-Draft P. Eardley
Intended status: Standards Track BT Intended status: Standards Track BT
Expires: February 21, 2015 M. Bagnulo Expires: July 9, 2015 M. Bagnulo
Universidad Carlos III de Madrid Universidad Carlos III de Madrid
J. Schoenwaelder J. Schoenwaelder
Jacobs University Bremen Jacobs University Bremen
August 20, 2014 January 05, 2015
Information Model for Large-Scale Measurement Platforms (LMAP) Information Model for Large-Scale Measurement Platforms (LMAP)
draft-ietf-lmap-information-model-02 draft-ietf-lmap-information-model-03
Abstract Abstract
This Information Model applies to the Measurement Agent within a This Information Model applies to the Measurement Agent within a
Large-Scale Measurement Platform. As such it outlines the Large-Scale Measurement Platform. As such it outlines the
information that is (pre-)configured on the MA or exists in information that is (pre-)configured on the MA or exists in
communications with a Controller or Collector within an LMAP communications with a Controller or Collector within an LMAP
framework. The purpose of such an Information Model is to provide a framework. The purpose of such an Information Model is to provide a
protocol and device independent view of the MA that can be protocol and device independent view of the MA that can be
implemented via one or more Control and Report protocols. implemented via one or more Control and Report protocols.
skipping to change at page 1, line 46 skipping to change at page 1, line 46
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on February 21, 2015. This Internet-Draft will expire on July 9, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Notation . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Notation . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. LMAP Information Model . . . . . . . . . . . . . . . . . . . 4 3. LMAP Information Model . . . . . . . . . . . . . . . . . . . 4
3.1. Information Structure . . . . . . . . . . . . . . . . . . 4 3.1. Pre-Configuration Information . . . . . . . . . . . . . . 7
3.2. Pre-Configuration Information . . . . . . . . . . . . . . 8 3.2. Configuration Information . . . . . . . . . . . . . . . . 9
3.3. Configuration Information . . . . . . . . . . . . . . . . 9 3.3. Instruction Information . . . . . . . . . . . . . . . . . 10
3.4. Instruction Information . . . . . . . . . . . . . . . . . 11 3.4. Logging Information . . . . . . . . . . . . . . . . . . . 13
3.5. Logging Information . . . . . . . . . . . . . . . . . . . 13 3.5. Capability and Status Information . . . . . . . . . . . . 15
3.6. Capability and Status Information . . . . . . . . . . . . 15 3.6. Reporting Information . . . . . . . . . . . . . . . . . . 16
3.7. Reporting Information . . . . . . . . . . . . . . . . . . 17 3.7. Common Objects . . . . . . . . . . . . . . . . . . . . . 18
3.8. Schedules . . . . . . . . . . . . . . . . . . . . . . . . 18 3.7.1. Schedules . . . . . . . . . . . . . . . . . . . . . . 18
3.9. Channels . . . . . . . . . . . . . . . . . . . . . . . . 21 3.7.2. Channels . . . . . . . . . . . . . . . . . . . . . . 21
3.10. Task Configurations . . . . . . . . . . . . . . . . . . . 22 3.7.3. Task Configurations . . . . . . . . . . . . . . . . . 22
3.11. Timing Information . . . . . . . . . . . . . . . . . . . 23 3.7.4. Timing Information . . . . . . . . . . . . . . . . . 24
3.11.1. Periodic Timing . . . . . . . . . . . . . . . . . . 24 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27
3.11.2. Calendar Timing . . . . . . . . . . . . . . . . . . 25 5. Security Considerations . . . . . . . . . . . . . . . . . . . 27
3.11.3. One-Off Timing . . . . . . . . . . . . . . . . . . . 26 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 28
3.11.4. Immediate Timing . . . . . . . . . . . . . . . . . . 26 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.11.5. Startup Timing . . . . . . . . . . . . . . . . . . . 26 7.1. Normative References . . . . . . . . . . . . . . . . . . 28
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 7.2. Informative References . . . . . . . . . . . . . . . . . 28
5. Security Considerations . . . . . . . . . . . . . . . . . . . 26 Appendix A. JSON Data Model Example . . . . . . . . . . . . . . 29
6. Appendix: JSON Example . . . . . . . . . . . . . . . . . . . 27 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 37
7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 35
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 35
8.1. Normative References . . . . . . . . . . . . . . . . . . 35
8.2. Informative References . . . . . . . . . . . . . . . . . 35
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 35
1. Introduction 1. Introduction
A large-scale measurement platform is a collection of components that A large-scale measurement platform is a collection of components that
work in a coordinated fashion to perform measurements from a large work in a coordinated fashion to perform measurements from a large
number of vantage points. The main components of a large-scale number of vantage points. The main components of a large-scale
measurement platform are the Measurement Agents (hereafter MAs), the measurement platform are the Measurement Agents (hereafter MAs), the
Controller(s) and the Collector(s). Controller(s) and the Collector(s).
The MAs are the elements actually performing the measurements. The The MAs are the elements actually performing the measurements. The
skipping to change at page 3, line 25 skipping to change at page 3, line 17
Collectors gather the results generated by the MAs. In a nutshell, Collectors gather the results generated by the MAs. In a nutshell,
the normal operation of a large-scale measurement platform starts the normal operation of a large-scale measurement platform starts
with the Controller instructing a set of one or more MAs to perform a 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 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 MAs execute the instructions from a Controller, and once they have
done so, they report the results of the measurements to one or more done so, they report the results of the measurements to one or more
Collectors. The overall framework for a Large Measurement platform Collectors. The overall framework for a Large Measurement platform
as used in this document is described in detail in as used in this document is described in detail in
[I-D.ietf-lmap-framework]. [I-D.ietf-lmap-framework].
A large-scale measurement platform involves basically three A large-scale measurement platform involves basically three types of
protocols, namely, a Control protocol between a Controller and the protocols, namely, a Control protocol (or protocols) between a
MAs, a Report protocol between the MAs and the Collector(s) and Controller and the MAs, a Report protocol (or protocols) between the
several measurement protocols between the MAs and Measurement Peers MAs and the Collector(s) and several measurement protocols between
(MPs), used to actually perform the measurements. In addition some the MAs and Measurement Peers (MPs), used to actually perform the
information is required to be configured on the MA prior to any measurements. In addition some information is required to be
communication with the initial Controller. configured on the MA prior to any communication with a Controller.
This document defines the information model for both the Control and This document defines the information model for both Control and the
the Report protocol along with pre-configuration information that is Report protocols along with pre-configuration information that is
required before communicating with the Controller, broadly named as required on the MA before communicating with the Controller, broadly
the LMAP Information Model. The measurement protocols are out of the named as the LMAP Information Model. The measurement protocols are
scope of this document. out of the scope of this document.
As defined in [RFC3444], the LMAP IM defines the concepts involved in As defined in [RFC3444], the LMAP Information Model (henceforth also
a large-scale measurement platform at a high level of abstraction, referred to as 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 independent of any specific implementation or actual protocol used to
exchange the information. It is expected that the proposed exchange the information. It is expected that the proposed
information model can be used with different protocols in different information model can be used with different protocols in different
measurement platform architectures and across different types of MA measurement platform architectures and across different types of MA
devices (e.g., home gateway, smartphone, PC, router). devices (e.g., home gateway, smartphone, PC, router).
The definition of an Information Model serves a number of purposes: The definition of an Information Model serves a number of purposes:
1. To guide the standardisation of one or more Control and Report 1. To guide the standardisation of one or more Control and Report
protocol and data model implementations protocols and data models
2. To enable high-level inter-operability between different Control 2. To enable high-level inter-operability between different Control
and Report protocols by facilitating translation between their and Report protocols by facilitating translation between their
respective data models such that a Controller could instruct sub- respective data models such that a Controller could instruct sub-
populations of MAs using different protocols populations of MAs using different protocols
3. To form agreement of what information needs to be held by an MA 3. To form agreement of what information needs to be held by an MA
and passed over the Control and Report interfaces and support the and passed over the Control and Report interfaces and support the
functionality described in the LMAP framework functionality described in the LMAP framework
skipping to change at page 4, line 28 skipping to change at page 4, line 19
This document use an object-oriented programming-like notation to This document use an object-oriented programming-like notation to
define the parameters (names/values) of the objects of the define the parameters (names/values) of the objects of the
information model. An optional field is enclosed by [ ], and an information model. An optional field is enclosed by [ ], and an
array is indicated by two numbers in angle brackets, <m..n>, where m 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 indicates the minimal number of values, and n is the maximum. The
symbol * for n means no upper bound. symbol * for n means no upper bound.
3. LMAP Information Model 3. LMAP Information Model
3.1. Information Structure
The information described herein relates to the information stored, The information described herein relates to the information stored,
received or transmitted by a Measurement Agent as described within received or transmitted by a Measurement Agent as described within
the LMAP framework [I-D.ietf-lmap-framework]. As such, some subsets the LMAP framework [I-D.ietf-lmap-framework]. As such, some subsets
of this information model are applicable to the measurement of this information model are applicable to the measurement
Controller, Collector and systems that pre-configure the Measurement Controller, Collector and any device management system that pre-
Agent. The information described in these models will be transmitted configures the Measurement Agent. The information described in these
by protocols using interfaces between the Measurement Agent and such models will be transmitted by protocols using interfaces between the
systems according to a Data Model. Measurement Agent and such systems according to a Data Model.
For clarity the information model is divided into six sections: For clarity the information model is divided into six sections:
1. Pre-Configuration Information. Information pre-configured on the 1. Pre-Configuration Information. Information pre-configured on the
Measurement Agent prior to any communication with other Measurement Agent prior to any communication with other
components of the LMAP architecture (i.e., the Controller, components of the LMAP architecture (i.e., the Controller,
Collector and Measurement Peers), specifically detailing how to Collector and Measurement Peers), specifically detailing how to
communicate with a Controller and whether the device is enabled communicate with a Controller and whether the device is enabled
to participate as an MA. to participate as an MA.
skipping to change at page 5, line 13 skipping to change at page 4, line 50
of further parameters about the MA (rather than the Tasks it of further parameters about the MA (rather than the Tasks it
should perform) that were not mandatory for the initial should perform) that were not mandatory for the initial
communication between the MA and a Controller. communication between the MA and a Controller.
3. Instruction Information. Information that is received by the MA 3. Instruction Information. Information that is received by the MA
from the Controller pertaining to the Tasks that should be from the Controller pertaining to the Tasks that should be
executed. This includes the task execution Schedules (other than executed. This includes the task execution Schedules (other than
the Controller communication Schedule supplied as the Controller communication Schedule supplied as
(pre)configuration information) and related information such as (pre)configuration information) and related information such as
the Task Configuration, communication Channels to Collectors and the Task Configuration, communication Channels to Collectors and
schedule Timing information. It also inlcudes Task Suppression schedule Timing information. It also includes Task Suppression
information that is used to over-ride normal Task execution information that is used to over-ride normal Task execution.
during emergency situations.
4. Logging Information. Information transmitted from the MA to the 4. Logging Information. Information transmitted from the MA to the
Controller detailing the results of any configuration operations Controller detailing the results of any configuration operations
along with error and status information from the operation of the along with error and status information from the operation of the
MA. MA.
5. Capability and Status Information. Information on the general 5. Capability and Status Information. Information on the general
status and capabilities of the MA. For example, the set of status and capabilities of the MA. For example, the set of
measurements that are supported on the device. measurements that are supported on the device.
skipping to change at page 6, line 6 skipping to change at page 5, line 42
The Information Model is divided into sub-sections for a number of The Information Model is divided into sub-sections for a number of
reasons. Firstly the grouping of information facilitates reader reasons. Firstly the grouping of information facilitates reader
understanding. Secondly, the particular groupings chosen are understanding. Secondly, the particular groupings chosen are
expected to map to different protocols or different transmissions expected to map to different protocols or different transmissions
within those protocols. within those protocols.
The granularity of data transmitted in each operation of the Control The granularity of data transmitted in each operation of the Control
and Report Protocols is not dictated by the Information Model. For and Report Protocols is not dictated by the Information Model. For
example, the Instruction object may be delivered in a single example, the Instruction object may be delivered in a single
operation. Alternatively, Schedules and Task Configurations may be operation. Alternatively, Schedules and Task Configurations may be
separated or even each Schdule/Task Configuration may be delivered separated or even each Schedule/Task Configuration may be delivered
individually. Similarly the Information Model does not dictate individually. Similarly the Information Model does not dictate
whether data is read, write, or read/write. For example, some whether data is read, write, or read/write. For example, some
Control Protocols may have the ability to read back Configuration and Control Protocols may have the ability to read back Configuration and
Instruction information which have been previosuly set on the MA. Instruction information which have been previosuly set on the MA.
Lastly, while some protocols may simply overwrite information (for Lastly, while some protocols may simply overwrite information (for
example refreshing the entire Instruction Information), other example refreshing the entire Instruction Information), other
protocols may have the ability to update or delete selected items of protocols may have the ability to update or delete selected items of
information. information.
The information in these six sections is captured by a number of The information in these six sections is captured by a number of
skipping to change at page 6, line 33 skipping to change at page 6, line 22
are used within the Instruction to specify what tasks should be are used within the Instruction to specify what tasks should be
performed, when, and how to direct their results. A Schedule is performed, when, and how to direct their results. A Schedule is
also used within the pre-Configuration and Configuration also used within the pre-Configuration and Configuration
information in order to execute the Task or Tasks required to information in order to execute the Task or Tasks required to
communicate with the Controller. communicate with the Controller.
2. Channels. A set of Channel objects are used to communicate with 2. Channels. A set of Channel objects are used to communicate with
a number of endpoints (i.e. the Controller and Collectors). Each a number of endpoints (i.e. the Controller and Collectors). Each
Channel object contains the information required for the Channel object contains the information required for the
communication with a single endpoint such as the target location communication with a single endpoint such as the target location
and security details. Channels are referenced from within and security details.
Schedules in order to say how Tasks should communicate.
3. Task Configurations. A set of Task Configurations is used to 3. Task Configurations. A set of Task Configurations is used to
configure the Tasks that are run by the MA. This includes the configure the Tasks that are run by the MA. This includes the
registry entry for the Task and any configuration parameters. registry entry for the Task and any configuration parameters.
Task Configurations are referenced from a Schedule in order to Task Configurations are referenced from a Schedule in order to
specify what Tasks the MA should execute. specify what Tasks the MA should execute.
4. Timings. A set of Timing objects that can be referenced from the 4. Timings. A set of Timing objects that can be referenced from the
Schedules. Each Schedule always references exactly one Timing Schedules. Each Schedule always references exactly one Timing
object. A Timing object specfies either a singleton or series of object. A Timing object specfies either a singleton or series of
time events. They are used to indicate when Tasks should be time events. They are used to indicate when Tasks should be
executed. executed.
The following diagram illustrates the structure in which these common The following diagram illustrates the structure in which these common
information objects are referenced. The references are achieved by information objects are referenced. The references are achieved by
each object (Channel, Task Configuration, Timing) being given a short each object (Channel, Task Configuration, Timing) being given a short
text name that is used by other objects. The objects shown in text name that is used by other objects. The objects shown in
parenthesis are part of the internal object structure of a Schedule. parenthesis are part of the internal object structure of a Schedule.
Schedule Schedule
|----------> Timing |----------> Timing
|----------> (Scheduled Tasks) |----------> (Scheduled Tasks)
|----------> Task Configuration |----------> Task Configuration
|----------> (Task Channels and downstream Tasks) |----------> Destination Tasks
|----------> Channels
|----------> Downstream Tasks
It should be clear that the top-level bahaviour of an MA is simply to It should be clear that the top-level bahaviour of an MA is simply to
execute Schedules. Every action referenced by a Schedule is defined execute Schedules. Every action referenced by a Schedule is defined
as a Task. As such, these actions are configured through Task as a Task. As such, these actions are configured through Task
Configurations and executed according to the Timing referenced by the Configurations and executed according to the Timing referenced by the
Schedule in which they appear. Tasks can implement a variety of Schedule in which they appear. Tasks can implement a variety of
different types of actions. While in terms of the Information Model, different types of actions. While in terms of the Information Model,
all Tasks have the same structure, it can help conceptually to think all Tasks have the same structure, it can help conceptually to think
of different Task categories: of different Task categories:
1. Measurement Tasks 1. Measurement Tasks measure some aspect of network performance or
traffic. They may also capture contextual information from the
A. Measurement Tasks measure some aspect of network performance MA device or network interfaces such the the device type or
or traffic available interface speed.
B. 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 2. Data Transfer Tasks
A. Reporting Tasks report the results or Measurement Tasks to A. Reporting Tasks report the results of Measurement Tasks to
Collectors Collectors
B. Control Task(s) implement the Control Protocol and B. Control Task(s) implement the Control Protocol and
communicate with the Controller. Depending on the Control communicate with the Controller. Depending on the Control
Protocol this may be a number of specialist tasks such as: Protocol there may be a number of specialist tasks such as:
Configuration Task; Instruction Task; Suppression Task; Configuration Task; Instruction Task; Suppression Task;
Capabilities Task; Logging Task etc. Capabilities Task; Logging Task etc.
3. Data Analysis Tasks can exist to analyse data from other 3. Data Analysis Tasks can exist to analyse data from other
Measurement Tasks locally on the MA Measurement Tasks locally on the MA
4. Data Management Tasks may exist to clean-up, filter or compress 4. Data Management Tasks may exist to clean-up, filter or compress
data on the MA such as Measurement Task results data on the MA such as Measurement Task results
3.2. Pre-Configuration Information 3.1. Pre-Configuration Information
This information is the minimal information that needs to be pre- This information is the minimal information that needs to be pre-
configured to the MA in order for it to successfully communicate with configured to the MA in order for it to successfully communicate with
a Controller during the registration process. The pre-configuration a Controller during the registration process. Some of the Pre-
information is a subset of the Configuration Information along with Configuration Information elements are repeated in the Configuration
some parameters that are not under the control of the LMAP framework Information in order to allow an LMAP Contoller to update these
(such as the the device identifier and device security credentials). items. The pre-configuration information also contains some elements
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 This Pre-Configuration Information needs to include a URL of the
initial Controller where configuration information can be retrieved initial Controller from where configuration information can be
along with the security information required for the communication communicated along with the security information required for the
including the certificate of the Controller (or the certificate of communication including the certificate of the Controller (or the
the Certification Authority which was used to issue the certificate certificate of the Certification Authority which was used to issue
for the Controller). All this is expressed as a Channel. While the certificate for the Controller). All this is expressed as a
multiple Channels may be provided in the pre-configuration Channel. While multiple Channels may be provided in the Pre-
information they must all be associated with a single Controller Configuration Information they must all be associated with a single
(e.g. over different interfaces or network protocols). Controller (e.g. over different interfaces or network protocols).
Where the MA pulls information from the Controller, the Pre- Where the MA pulls information from the Controller, the Pre-
Configuration Information also needs to contain the timing of the Configuration Information also needs to contain the timing of the
communication with the Controller as well as the nature of the communication with the Controller as well as the nature of the
communication itself (such as the protocol and data to be communication itself (such as the protocol and data to be
transfered). The timing is given as a Schedule that executes the transfered). The timing is given as a Schedule that executes the
Task(s) responsible for communication with the Controller. It is Task(s) responsible for communication with the Controller. It is
this Task (or Tasks) that implement the Control protocol between the this Task (or Tasks) that implement the Control protocol between the
MA and the Controller. The Task(s) may take additional parameters in MA and the Controller and utlises the Channel information. The
which case a Task Configuration can also be included. Task(s) may take additional parameters in which case a Task
Configuration can also be included.
Even where information is pushed to the MA from the Controller Even where information is pushed to the MA from the Controller
(rather than pulled by the MA), a Schedule still needs to be (rather than pulled by the MA), a Schedule still needs to be
supplied. In this case the Schedule will simply execute a Controller supplied. In this case the Schedule will simply execute a Controller
listener task when the MA is started. A Channel is still required listener task when the MA is started. A Channel is still required
for the MA to establish secure communication with the Controller. for the MA to establish secure communication with the Controller.
It can be seen that these Channels, Schedules and Task Configurations It can be seen that these Channels, Schedules and Task Configurations
for the initial MA-Controller communication are no different in terms for the initial MA-Controller communication are no different in terms
of the Information Model to any other Channel, Schedule or Task of the Information Model to any other Channel, Schedule or Task
Configuration that might execute a Measurement Task or report the Configuration that might execute a Measurement Task or report the
measurement results (as described later). measurement results (as described later).
The MA may be pre-configured with an MA ID, or may use a Device ID in The MA may 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 the first Controller contact before it is assigned an MA ID. The
Device ID may be a MAC address or some other device identifier Device ID may be a MAC address or some other device identifier
expressed as a URN. If the MA ID is not provided at this stage then expressed as a URN. If the MA ID is not provided at this stage then
it must be provided by the Controller during Configuration. it must be provided by the Controller during Configuration.
Detail of the information model elements: Detail of the information model elements:
// MA pre-configuration minimal information to communicate initially with Controller // MA pre-configuration minimal information to communicate
// initially with Controller
object { object {
[uuid ma-agent-id;] [uuid ma-agent-id;]
ma-task-obj ma-control-tasks<1..*>; ma-task-obj ma-control-tasks<1..*>;
ma-channel-obj ma-control-channels<1..*>; ma-channel-obj ma-control-channels<1..*>;
ma-schedule-obj ma-control-schedules<1..*>; ma-schedule-obj ma-control-schedules<1..*>;
[urn ma-device-id;] [urn ma-device-id;]
credentials ma-credentials; credentials ma-credentials;
} ma-config-obj; } ma-config-obj;
The detail of the Channel and Schedule objects are described later The details of the Channel and Schedule objects are described later
since they are common to several parts of the information model. since they are common to several parts of the information model.
3.3. Configuration Information 3.2. Configuration Information
During registration or at any later point at which the MA contacts During registration or at any later point at which the MA contacts
the Controller (or vice-versa), the choice of Controller, details for the Controller (or vice-versa), the choice of Controller, details for
the timing of communication with the Controller or parameters for the the timing of communication with the Controller or parameters for the
communication Task(s) can be changed (as captured by the Channels, communication Task(s) can be changed (as captured by the Channels,
Schedules and Task Configurations objects). For example the pre- Schedules and Task Configurations objects). For example the pre-
configured Controller (specified as a Channel or Channels) may be configured Controller (specified as a Channel or Channels) may be
replaced with a specific Controller that is more appropriate to the over-riden with a specific Controller that is more appropriate to the
MA device type, location or characteristics of the network (e.g. MA device type, location or characteristics of the network (e.g.
access technology type or broadband product). The initial access technology type or broadband product). The initial
communication Schedule may be replaced with one more relevant to communication Schedule may be over-ridden with one more relevant to
routine communications between the MA and the Controller. routine communications between the MA and the Controller.
While some Control protocols and uses may only use a single Schedule, While some Control protocols may only use a single Schedule, other
other protocols and uses may uses several Schedules (and related data protocolsmay use several Schedules (and related data transfer Tasks)
transfer Tasks) to update the Configuration Information, transfer the to update the Configuration Information, transfer the Instruction
Instruction Information, transfer Capability and Status Information Information, transfer Capability and Status Information and send
and send other information to the Controller such as log or error other information to the Controller such as log or error
notifications. Multiple Channels may be used to communicate with the notifications. Multiple Channels may be used to communicate with the
same Controller over multiple interfaces (e.g. to send logging same Controller over multiple interfaces (e.g. to send logging
information over a different network). information over a different network).
In addition the MA will be given further items of information that In addition the MA will be given further items of information that
relate specifically to the MA rather than the measurements it is to 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 conduct or how to report results. The assignment of an ID to the MA
is mandatory. If the MA Agent ID was not optionally provided during is mandatory. If the MA Agent ID was not optionally provided during
the pre-configuration then one must be provided by the Controller the pre-configuration then one must be provided by the Controller
during Configuration. Optionally a Group ID may also be given which during Configuration. Optionally a Group ID may also be given which
skipping to change at page 10, line 16 skipping to change at page 9, line 51
anonymous, which may be particularly useful to prevent tracking of anonymous, which may be particularly useful to prevent tracking of
mobile MA devices. mobile MA devices.
Optionally an MA can also be configured to stop executing any Optionally an MA can also be configured to stop executing any
Instruction Schedule if the Controller is unreachable. This can be Instruction Schedule if the Controller is unreachable. This can be
used as a fail-safe to stop Measurement and other Tasks being used as a fail-safe to stop Measurement and other Tasks being
conducted when there is doubt that the Instruction Information is conducted when there is doubt that the Instruction Information is
still valid. This is simply represented as a time window in still valid. This is simply represented as a time window in
milliseconds since the last communication with the Controller after milliseconds since the last communication with the Controller after
which Instruction Schedules are to be suspended. The appropriate which Instruction Schedules are to be suspended. The appropriate
vaue of the time window will depend on the specified communication value of the time window will depend on the specified communication
Schedule with the Controller and the duration for which the system is Schedule with the Controller and the duration for which the system is
willing to tolerate continued operation with potentially stale willing to tolerate continued operation with potentially stale
Instruction Information. Instruction Information.
While pre-configuration is persistent upon device reset or power While Pre-Configuration Information is persistent upon device reset
cycle due to its very nature, the persistency of the addtional or power cycle, the persistency of the Configuration Information may
configuration information may be control protocol dependent. Some be device dependent. Some devices may revert back to their pre-
protocols may assume that reset devices will revert back to their configuration state upon reboot or factory reset, while other devices
pre-configuration state, while other protocols may assume that all may store all Configuration and Instruction information in persistent
configuration and instruction information is held in persistent storage. A Controller can check whether an MA has the latest
storage. Configuration and Instruction information by examing the Capability
and Status information for the MA.
It should be noted that control shedules and tasks cannot be It should be noted that control shedules and tasks cannot be
suppressed as evidenced by the lack of suppression information in the suppressed as evidenced by the lack of suppression information in the
Configuration. The control schedule must only reference tasks listed Configuration. The control schedule must only reference tasks listed
as control tasks. Any suppress-by-default flag against control tasks as control tasks (i.e. within the Configuration information). Any
will be ignored. suppress-by-default flag against control tasks will be ignored.
Detail of the additional and updated information model elements: Detail of the additional and updated information model elements:
// MA Configuration // MA Configuration
object { object {
uuid ma-agent-id; uuid ma-agent-id;
[ma-task-obj ma-control-tasks<0..*>;] ma-task-obj ma-control-tasks<1..*>;
ma-channel-obj ma-control-channels<1..*>; ma-channel-obj ma-control-channels<1..*>;
[ma-schedule-obj ma-control-schedules<0..*>]; ma-schedule-obj ma-control-schedules<1..*>;
[urn ma-device-id;] [urn ma-device-id;]
credentials ma-credentials; credentials ma-credentials;
[string ma-group-id;] [string ma-group-id;]
[boolean ma-report-ma-id-flag;] [boolean ma-report-ma-id-flag;]
[int ma-control-channel-failure-threshold;] [int ma-control-channel-failure-threshold;]
} ma-config-obj; } ma-config-obj;
3.4. Instruction Information 3.3. Instruction Information
The Instruction information model has four sub-elements: The Instruction information model has four sub-elements:
1. Instruction Task Configurations 1. Instruction Task Configurations
2. Report Channels 2. Report Channels
3. Instruction Schedules 3. Instruction Schedules
4. Suppression 4. Suppression
The Instruction supports the exceution of all Tasks on the MA except The Instruction supports the execution of all Tasks on the MA except
those that deal with communication with the Controller (specified in those that deal with communication with the Controller (specified in
(pre)configuration information). The Tasks are configured in (pre-)configuration information). The Tasks are configured in
Instruction Task Configurations and inlcuded by reference in Instruction Task Configurations and included by reference in
Instruction Schdules that specify when to execute them. The results Instruction Schdules that specify when to execute them. The results
are communicated to other Tasks or over Report Channels. Suppression can be communicated to other Tasks or a Task may implement a
is used to temporarily stop the excution of new Tasks as specified by Reporting Protocol and communicate results over Report Channels.
the Instruction Schedules (and optionaly to stop ongoing Tasks). Suppression is used to temporarily stop the excution of new Tasks as
specified by the Instruction Schedules (and optionally to stop
ongoing Tasks).
A Task Configuration is used to configure the optional parameters of A Task Configuration is used to configure the mandatory and optional
a Task. It also serves to instruct the MA about the Task including parameters of a Task. It also serves to instruct the MA about the
the ability to resolve the Task to an executable and specifying the Task including the ability to resolve the Task to an executable and
schema for the Task parameters. specifying the schema for the Task parameters.
A Report Channel defines how to communicate with a single remote A Report Channel defines how to communicate with a single remote
system specified by a URL. A Report Channel is used to send results system specified by a URL. A Report Channel is used to send results
to single Collector but is no different in terms of the Information to single Collector but is no different in terms of the Information
Model to the Control Channel used to transfer information between the Model to the Control Channel used to transfer information between the
MA and the Controller. Several Report Channels can be defined to MA and the Controller. Several Report Channels can be defined to
enable results to be split or duplicated across different enable results to be split or duplicated across different
destinations. A single Channel can also be used by multiple destinations. A single Channel can be used by multiple (reporting)
Schedules to transfer data at different cycles to the same Collector. Task Configurations to transfer data to the same Collector. A single
E.g. a single Collector may receive data at three different cycle Reporting Task Configuration can also be included in multiple
rates, one Schedule reporting hourly, another reporting daily and a Schedules. E.g. a single Collector may receive data at three
third specifying that results should be sent immediately for on- different cycle rates, one Schedule reporting hourly, another
demand measurement tasks. Alternatively multiple Report Channels can reporting daily and a third specifying that results should be sent
be used to send Measurement Task results to different Collectors. immediately for on-demand measurement tasks. Alternatively multiple
The details of the Channel element is described later as it is common Report Channels can be used to send Measurement Task results to
to several objects. different Collectors. The details of the Channel element is
described later as it is common to several objects.
Instruction Schedules specify which Tasks to execute according to a Instruction Schedules specify which Tasks to execute according to a
given Timing (that can execute a single or repeated series of Tasks). given Timing (that can execute a single or repeated series of Tasks).
The Schedule also specifies how to deal with Task inputs and outputs The Schedule also specifies how to link Tasks output data to other
- e.g. sending selected outputs to other Tasks or specifying the scheduled Tasks - i.e. sending selected outputs to other Tasks.
Report Channels that should be used to report results to Collectors.
Measurement Suppression information is used to over-ride the Measurement Suppression information is used to over-ride the
Instruction Schedule and temporarily stop measurements or other Tasks Instruction Schedule and temporarily stop measurements or other Tasks
from running on the MA for a defined or indefinite period. While from running on the MA for a defined or indefinite period. While
conceptually measurements can be stopped by simply removing them from conceptually measurements can be stopped by simply removing them from
the Measurement Schedule, splitting out separate information on the Measurement Schedule, splitting out separate information on
Measurement Suppression allows this information to be updated on the Measurement Suppression allows this information to be updated on the
MA on a different timing cycle or protocol implementation to the MA on a different timing cycle or protocol implementation to the
Measurement Schedule. It is also considered that it will be easier Measurement Schedule. It is also considered that it will be easier
for a human operator to implement a temporary explicit suppression for a human operator to implement a temporary explicit suppression
skipping to change at page 12, line 35 skipping to change at page 12, line 23
targetted. Support for disabling specific Schedules allows for targetted. Support for disabling specific Schedules allows for
particularly heavy cycles or sets of less essential Measurement Tasks particularly heavy cycles or sets of less essential Measurement Tasks
to be suppressed quickly and effectively. Note that Suppression has to be suppressed quickly and effectively. Note that Suppression has
no effect on either Controller Tasks or Controller Schedules. no effect on either Controller Tasks or Controller Schedules.
When no tasks or schedules are explicitly listed, all Instruction When no tasks or schedules are explicitly listed, all Instruction
tasks will be suppressed (or not) as indicated by the suppress-by- tasks will be suppressed (or not) as indicated by the suppress-by-
default flag in the Task Configuration. If tasks or schedules are default flag in the Task Configuration. If tasks or schedules are
listed explicitly then only these listed tasks or schedules will be listed explicitly then only these listed tasks or schedules will be
suppressed regardless of the suppress-by-default flag. If both suppressed regardless of the suppress-by-default flag. If both
individual tasks and individual schedules are listed then the union individual tasks and individual schedules are listed then only the
of these options is considered - i.e. the listed shcedules plus the listed schedules, plus the listed tasks where present in other
listed tasks where present in other schedules. schedules, will be suppressed regardless of the suppress-by-default
flag.
Suppression stops new Tasks from executing. In addtion, the Suppression stops new Tasks from executing. In addtion, the
Suppression information also supports an additional Boolean that is Suppression information also supports an additional Boolean that is
used to select whether on-going tasks are also to be terminated. used to select whether on-going tasks are also to be terminated.
Unsuppression is achieved through either overwriting the Measurement Unsuppression is achieved through either overwriting the Measurement
Suppression information (e.g. changing 'enabled' to False) or through Suppression information (e.g. changing 'enabled' to False) or through
the use of an End time such that the Measurement Suppression will no 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 longer be in effect beyond this time. The datetime format used for
all elements in the information model (e.g. the suppression start and all elements in the information model (e.g. the suppression start and
end dates) MUST conform to RFC 3339 [RFC3339] and ISO8601. end dates) MUST conform to RFC 3339 [RFC3339].
The goal when defining these four different elements is to allow each The goal when defining these four different elements is to allow each
part of the information model to change without affecting the other part of the information model to change without affecting the other
three elements. For example it is envisaged that the Report Channels three elements. For example it is envisaged that the Report Channels
and the set of Task Configurations will be relatively static. The and the set of Task Configurations will be relatively static. The
Instruction Schedule, on the other hand, is likely to be more Instruction Schedule, on the other hand, is likely to be more
dynamic, as the measurement panel and test frequency are changed for dynamic, as the measurement panel and test frequency are changed for
various business goals. Another example is that measurements can be various business goals. Another example is that measurements can be
suppressed with a Suppression command without removing the existing suppressed with a Suppression command without removing the existing
Instruction Schedules that would continue to apply after the Instruction Schedules that would continue to apply after the
Suppression expires or is removed. In terms of the Controller-MA Suppression expires or is removed. In terms of the Controller-MA
communication this can reduce the data overhead. It also encourages communication this can reduce the data overhead. It also encourages
the re-use of the same standard Task Configurations and Reporting the re-use of the same standard Task Configurations and Reporting
Channels to help ensure consistency and reduce errors. Channels to help ensure consistency and reduce errors.
Definition of the information model elements: Definition of the information model elements:
// Instruction to the MA to configure Tasks, Channels, Schedules and Suppression // Instruction to the MA to configure Tasks, Channels,
//Schedules and Suppression
object { object {
ma-task-obj ma-instruction-tasks<0..*>; ma-task-obj ma-instruction-tasks<0..*>;
ma-channel-obj ma-report-channels<0..*>; ma-channel-obj ma-report-channels<0..*>;
ma-schedule-obj ma-instruction-schedules<0..*>; ma-schedule-obj ma-instruction-schedules<0..*>;
ma-suppression-obj ma-suppression; ma-suppression-obj ma-suppression;
} ma-instruction-obj; } ma-instruction-obj;
// Suppression object to temporarily override new task execution in Instructions and optionally stop currently running tasks // Suppression object to temporarily override new task execution
// in Instructions and optionally stop currently running tasks
object { object {
boolean ma-suppression-enabled; boolean ma-suppression-enabled;
[boolean ma-suppression-stop-ongoing-tasks;] // default: false [boolean ma-suppression-stop-ongoing-tasks;]
[datetime ma-suppression-start;] // default: immediate // default: false
[datetime ma-suppression-end;] // default: indefinite [datetime ma-suppression-start;] // default: immediate
[string ma-suppression-task-names<0..*>;] [datetime ma-suppression-end;] // default: indefinite
// default: all tasks if [string ma-suppression-task-names<0..*>;]
// ma-suppression-task-names is empty // default: all tasks if
[string ma-suppression-schedule-names<0..*>;] // ma-suppression-task-names is empty
// default: all schedules if [string ma-suppression-schedule-names<0..*>;]
// ma-suppression-schedule-names is empty // default: all schedules if
} ma-suppression-obj; // ma-suppression-schedule-names is empty
} ma-suppression-obj;
3.5. Logging Information 3.4. Logging Information
The MA may report on the success or failure of Configuration or The MA may report on the success or failure of Configuration or
Instruction communications from the Controller. In addition further Instruction communications from the Controller. In addition further
operational logs may be produced during the operation of the MA and operational logs may be produced during the operation of the MA and
updates to capabilities may also be reported. Reporting this updates to capabilities may also be reported. Reporting this
information is achieved simply and flexibly in exactly the same information is achieved in exactly the same manner as scheduling any
manner as any other Task. We make no distinction between a other Task. We make no distinction between a Measurement Task
Measurement Task conducting an active or passive network measurement conducting an active or passive network measurement and one which
and one which solely retrieves static or dynamic information from the solely retrieves static or dynamic information from the MA such as
MA such as capabilities or logging information. One or more logging capabilities or logging information. One or more logging tasks can
tasks can be programmed or configured to capture subsets of the be programmed or configured to capture subsets of the Logging
Logging Information. These logging tasks are then executed by Information. These logging tasks are then executed by Schedules
Schedules which also specify that the resultant data is to be which also specify that the resultant data is to be transferred over
transferred over the Controller Channels. the Controller Channels.
The type of Logging Information will fall into three different The type of Logging Information will fall into three different
categories: categories:
1. Success/failure/warning messages in response to information 1. Success/failure/warning messages in response to information
updates from the Controller. Failure messages could be produced updates from the Controller. Failure messages could be produced
due to some inability to receive or parse the Controller due to some inability to receive or parse the Controller
communication, or if the MA is not able to act as instructed. communication, or if the MA is not able to act as instructed.
For example: For example:
skipping to change at page 15, line 5 skipping to change at page 14, line 45
* "Collector 'collector.example.com' not responding" * "Collector 'collector.example.com' not responding"
* "Unexpected restart" * "Unexpected restart"
* "Suppression timeout" * "Suppression timeout"
* "Failed to execute Measurement Task Configuration H" * "Failed to execute Measurement Task Configuration H"
3. Status updates from the MA. For example: 3. Status updates from the MA. For example:
* "Interface added: eth3 " * "Device interface added: eth3 "
* "Supported measurements updated" * "Supported measurements updated"
* "New IP address on eth0: xxx.xxx.xxx.xxx" * "New IP address on eth0: xxx.xxx.xxx.xxx"
This Information Model document does not detail the precise format of This Information Model document does not detail the precise format of
logging information since it is to a large extent protocol and MA logging information since it is to a large extent protocol and MA
specific. However, some common information can be identified. specific. However, some common information can be identified.
MA Logging information model elements: MA Logging information model elements:
// Logging object // Logging object
object { object {
uuid ma-log-agent-id; uuid ma-log-agent-id;
datetime ma-log-event-time; datetime ma-log-event-time;
code ma-log-code; code ma-log-code;
string ma-log-description; string ma-log-description;
} ma-log-obj; } ma-log-obj;
3.6. Capability and Status Information 3.5. Capability and Status Information
The MA will hold Capability Information that can be retrieved by a The MA will hold Capability Information that can be retrieved by a
Controller. Capabilities include the interface details available to Controller. Capabilities include the device interface details
Measurement Tasks and Channels as well as the set of Measurement available to Measurement Tasks as well as the set of Measurement
Tasks/Roles that are actually installed or available on the MA. Tasks/Roles (specified by a registry entry) that are actually
Status information includes the times that operations were last installed or available on the MA. Status information includes the
performed such as contacting the Controller or producing Reports. times that operations were last performed such as contacting the
Controller or producing Reports.
MA Status information model elements: MA Status information model elements:
// Main MA Status information object // Main MA Status information object
object { object {
uuid ma-agent-id; uuid ma-agent-id;
urn ma-device-id; urn ma-device-id;
string ma-hardware; string ma-hardware;
string ma-firmware; string ma-firmware;
string ma-version; string ma-version;
ma-interface-obj ma-interfaces<0..*>; ma-interface-obj ma-interfaces<0..*>;
datetime ma-last-measurement; datetime ma-last-task;
datetime ma-last-report; datetime ma-last-report;
datetime ma-last-instruction; datetime ma-last-instruction;
datetime ma-last-configuration; datetime ma-last-configuration;
[ma-condition-obj ma-conditions<0..*>;] [ma-condition-obj ma-conditions<0..*>;]
ma-task-capability-obj ma-supported-tasks<0..*>; ma-task-capability-obj ma-supported-tasks<0..*>;
} ma-status-obj; } ma-status-obj;
// Additional status conditions // Additional status conditions
object { object {
string ma-condition-code; string ma-condition-code;
string ma-condition-text; string ma-condition-text;
} ma-condition-obj } ma-condition-obj
// Interface information // Interface information
object { object {
skipping to change at page 16, line 49 skipping to change at page 16, line 28
[ip-address ma-interface-ip-addresses<0..*>]; [ip-address ma-interface-ip-addresses<0..*>];
[ip-address ma-interface-gateways<0..*>;] [ip-address ma-interface-gateways<0..*>;]
[ip-address ma-interface-dns-servers<0..*>;] [ip-address ma-interface-dns-servers<0..*>;]
} ma-interface-obj; } ma-interface-obj;
// Supported tasks/roles // Supported tasks/roles
object { object {
string ma-task-name; string ma-task-name;
uri ma-task-registry; uri ma-task-registry;
string ma-task-role;
} ma-task-capability-obj; } ma-task-capability-obj;
3.7. Reporting Information 3.6. Reporting Information
At a point in time specified by a Schedule, the MA will execute a At a point in time specified by a Schedule, the MA will execute a
task or tasks that communicate a set of measurement results to the task or tasks that communicate a set of measurement results to the
Collector. Some of these Tasks (notably Reporting Tasks) will Collector. Some of these Tasks (notably Reporting Tasks) will
understand how to transmit task results over a specified Report understand how to transmit task results over a specified Report
Channel to a Collector. Where to send the data is defined within the Channel to a Collector. Where to send the data is defined within the
Schedule information. Task Configuration for the Reporting Task.
It should be noted that the output from Tasks does not need to be It should be noted that the output from Tasks does not need to be
sent to communication Channels. It can alternatively, or sent to communication Channels. It can alternatively, or
additionally, be sent to other Tasks on the MA. This facilitates additionally, be sent to other Tasks on the MA. This facilitates
using a first Measurement Task to control the operation of a later using a first Measurement Task to control the operation of a later
Measurement Task (such as first probing available line speed and then Measurement Task (such as first probing available line speed and then
adjusting the operation of a video testing measurement) and also to adjusting the operation of a video testing measurement) and also to
allow local processing of data to output alarms (e.g. when allow local processing of data to output alarms (e.g. when
performance drops from earlier levels). Of course, subsequent Tasks performance drops from earlier levels). Of course, subsequent Tasks
also include Tasks that implement the reporting protocol(s) and also include Tasks that implement the reporting protocol(s) and
transfer data to one or more Collector(s). transfer data to one or more Collector(s).
The report is structured hierarchically to avoid repetition of report The report is structured hierarchically to avoid repetition of report
header and Measurement Task Configuration information. The report header and Measurement Task Configuration information. The report
starts with the timestamp of the report generation on the MA and starts with the timestamp of the report generation on the MA and
details about the MA including the optional Measurement Agent ID and details about the MA including the optional Measurement Agent ID and
Group ID (controlled by the Configuration Information). Group ID (controlled by the Configuration Information).
Much of the report Information is optional and will depend on the
implementation of the Reporting Task and any parameters defined in
the Task Configuration for the Reporting Task. For example some
Reporting Tasks may choose not to include the Measurement Task
Configuration or Sscheduled task parameters, while others may do so
dependent on the Controller setting a configurable parameter in the
Task Configuration.
It is possible for a Reporting Task to send just the Report header
(datetime and optional agent ID and/or Group ID) if no measurement
data is available. Whether to send such empty reports again is
dependent on the implementation of the Reporting Task and potential
Task Configuration parameter.
The handling of measurement data on the MA before generating a Report
and transfer from the MA to the Collector is dependent on the
implementation of the device, MA and/or scheduled Tasks and not
defined by the LMAP standards. Such decisions may include limits to
the measurement data storage and what to do when such available
storage becomes depleted.
No context information, such as line speed or broadband product are No context information, such as line speed or broadband product are
included within the report header information as this data is included within the report header information as this data is
reported by individual tasks at the time they execute. Either a reported by individual tasks at the time they execute. Either a
Measurement Task can report contextual parameters that are relevant Measurement Task can report contextual parameters that are relevant
to that particular measurement, or specific tasks can be used to to that particular measurement, or specific tasks can be used to
gather a set of contextual and environmental data. at certain times gather a set of contextual and environmental data. at certain times
independent of the reporting schedule. independent of the reporting schedule.
After the report header information the results are reported grouped After the report header information the results are reported grouped
according to different Measurement Task Configurations. Each Task according to different Measurement Task Configurations. Each Task
section starts with replicating the Measurement Task Configuration section optionally starts with replicating the Measurement Task
information before the result headers (titles for data columns) and Configuration information before the result headers (titles for data
the result data rows. columns) and the result data rows.
The result row data inlcudes a time for the start of the measurement The result row data includes a time for the start of the measurement
and optionally an end time where the duration also needs to be and optionally an end time where the duration also needs to be
considered in the data analysis. The result data rows may optionally considered in the data analysis.
include an indication of the cross-traffic. Cross traffic is defined
as the total number of Bytes both upstream and downstream of non- Some Measurement Tasks may optionally include an indication of the
measurement traffic passing through the interfaces used by a cross-traffic although the meaning a definition of cross-traffic is
Measurement Task during the measurement period. The specific left up to each individual Measurement Task. Some Measurement Tasks
Measurement Task may also output other environmental measures in may also output other environmental measures in addtion to cross-
addtion to cross-traffic such as CPU utlisation or interface speed. traffic such as CPU utlisation or interface speed.
The encoding of this information will vary dependent upon the data
model chosen for the Report Protocol.
Where the Configuration and Instruction information represent Where the Configuration and Instruction information represent
information transmitted via the Control Protocol, the Report information transmitted via the Control Protocol, the Report
represents the information that is transmitted via the Report represents the information that is transmitted via the Report
Protocol. It is constructed at the time of sending a report and Protocol. It is constructed at the time of sending a report and
represents the inherent structure of the information that is sent to represents the inherent structure of the information that is sent to
the Collector. the Collector.
Information model elements: Information model elements:
// Main Report object with report header information // Main Report object with report header information
object { object {
datetime ma-report-date; datetime ma-report-date;
[uuid ma-report-agent-id;] [uuid ma-report-agent-id;]
[string ma-report-group-id;] [string ma-report-group-id;]
ma-report-task-obj ma-report-tasks<0..*>; [ma-report-task-obj ma-report-tasks<0..*>];
} ma-report-obj; } ma-report-obj;
// Report task header information // Report task header information
object { object {
ma-task-obj ma-report-task-config; string ma-report-task-name;
[uri ma-report-task-registry-entry;]
[name-value-pair ma-report-scheduled-task-options<0..*>];
[string ma-report-task-cycle-id;]
string ma-report-task-column-labels<0..*>; string ma-report-task-column-labels<0..*>;
ma-result-row-obj ma-report-task-rows<0..*>; ma-result-row-obj ma-report-task-rows<0..*>;
} ma-report-task-obj; } ma-report-task-obj;
// Report tasks result rows // Report tasks result rows
object { object {
datetime ma-report-result-start-time; datetime ma-report-result-start-time;
[datetime ma-report-result-end-time;] [datetime ma-report-result-end-time;]
string ma-report-result-conflicting-tasks<0..*>; string ma-report-result-conflicting-tasks<0..*>;
[int ma-report-result-cross-traffic;] // Bytes of non-measurement traffic data ma-report-result-values<0..*>;
// on measurement interface during measurement period } ma-result-row-obj;
data ma-report-result-values<0..*>;
} ma-result-row-obj;
3.8. Schedules 3.7. Common Objects
3.7.1. Schedules
A Schedule specifies the execution of a single or repeated series of A Schedule specifies the execution of a single or repeated series of
Tasks. Each Schedule contains basically two elements: a list of Tasks. Each Schedule contains basically two elements: a list of
Tasks to be executed and a timing object for the Schedule. The Tasks to be executed and a timing object for the Schedule. The
Schedule states what Tasks to run (with what configuration), how to Schedule states what Tasks to run (with what configuration) and when
report the results, and when to run the Tasks. to run the Tasks.
Multiple Tasks in the list of a single Measurement Schedule will be Multiple Tasks in the list of a single Measurement Schedule will be
executed in order with minimal gaps. Tasks in different Schedules executed in order with minimal gaps. Tasks in different Schedules
can execute in parallel with such conflicts beings reported in the execute in parallel with such conflicts being reported in the
Reporting Information. Reporting Information. If two or more Schedules have the same start
time, then the two will execute in parallel. There is no mechanism
to prioritise one schedule over another or to mutex schduled tasks.
As well as specifying which Tasks to execute, the Schedule also As well as specifying which Tasks to execute, the Schedule also
specifies where to send the data outputs from each Task. Specifying specifies how to link the data outputs from each scheduled task to
this within the Schedule allows the highest level of flexibility other scheduled tasks. Specifying this within the Schedule allows
since it is even possible to send the output from different the highest level of flexibility since it is even possible to send
executions of the same Task to different destinations. Since a the output from different executions of the same Task Configuration
single Task may have multiple outputs, the Schedule can independently to different destinations. Since a single Task may have multiple
specify which outputs go to which destinations. For example, a outputs, the Schedule can independently specify which outputs go to
Measurement Task might report routine results to a data Reporting which destinations. For example, a Measurement Task might report
Task that communicates hourly via the Broadband PPP interface, but routine results to a data Reporting Task that communicates hourly via
also outputs emergency conditions via an alarm Reporting Task the Broadband PPP interface, but also outputs emergency conditions
communicating immediately over a GPRS channel. via an alarm Reporting Task communicating immediately over a GPRS
channel. Note that task-to-task data transfer is always specified in
The interface options for a Task are either another downstream Task association with the scheduled execution of the sending task - there
or a Channel. The output of a Task can be sent to another Task. For is no need for a corresponding input specification for the receiving
example a Measurement Task may send its output to a data transfer task. While it is likely that an MA implementation will use a queue
Task that reports the batched data to a Collector at a later time. mechanism between the scheduled tasks, this Information Model does
Alternatively the output from a Measurement Task may be fed to an not mandate or define a queue, or any potential associated parameters
alarm processing task that monitors the results of a series of such as storage size and retention policies.
Measurement Tasks.
Only some Tasks will understand how to send/receive data to/from
Channels using the Reporting/Control protocol. Any Task that does
not implement either the Reporting or Control protocol will not have
any channel interfaces to configure. Instead results should be
passed to a Reporting Task that has the appropriate Collector
specified as a Channel.
When a task is referenced by a schedule there will be a simultaneous When specifying the task to execute withi the Schedule, it is
definition of which (if any) channels to use and which (if any) other possible to add to the task configuration option parameters. This
downstream tasks to send data to. Note that task-to-task data allows the Task Configuration to deterimine the common
transfer is always specified in association with the scheduled characteristics of a Task, while selected parameters (e.g. the test
execution of the sending task - there is no need for a corresponding target URL) are defined within the schedule. A single Tasks
input specification for the receiving task. Configuration can even be used multiple times in the same schedule
with different additional parameters. This allows for effciency in
creating and transferring the Instruction. Note that the semantics
of what happens if an option is defined multiple times (either in the
Task Configuration, Schedule or in both) is not standardised and will
depend upon the Task. For example some tasks may legitimately take
multiple values for a single parameter.
Example: A Schedule references a single Measurement Task Example: A Schedule references a single Measurement Task
Configuration for the UDP latency. It specifies that results are Configuration for the UDP latency. It specifies that results are
to be sent to a Reporting Task. This Reporting Task is executed to be sent to a scheduled Reporting Task. This Reporting Task is
by a separate Schedule that specifies that it should run hourly at executed by a separate Schedule that specifies that it should run
5 minutes past the hour. When run this Reporting Task takes the hourly at 5 minutes past the hour. When run this Reporting Task
data generated by the UDP latency Task as well as any other data takes the data generated by the UDP latency Task as well as any
to be included in the hourly report and transfers it to the other data to be included in the hourly report and transfers it to
Collector over the Report Channel specified within its own the Collector over the Report Channel specified within its own
Schedule. Schedule.
// main Schedule object with Timing and list of Scheduled Tasks // main Schedule object with Timing and list of Scheduled Tasks
object { object {
string ma-schedule-name; string ma-schedule-name;
ma-sched-task-obj ma-schedule-tasks<0..*>; ma-sched-task-obj ma-schedule-tasks<0..*>;
ma-timing-obj ma-schedule-timing; ma-timing-obj ma-schedule-timing;
} ma-schedule-obj; } ma-schedule-obj;
// Scheduled Task object with reference (by name string) to Task Configuration to execute and mapping // Scheduled Task object with reference (by name string) to Task
// to channels and onward tasks // Configuration and mappings of data outputs to destination tasks
object { object {
string ma-schedule-task-name; string ma-schedule-task-name;
[ma-sched-channels-obj ma-schedule-channels<0..*>;] [name-value-pair ma-schedule-task-options<0..*>];
[ma-sched-downstream-tasks-obj ma-schedule-downstream-tasks<0..*>;] [ma-sched-downstream-tasks-obj ma-schedule-destination-tasks<0..*>;]
} ma-sched-task-obj; } ma-sched-task-obj;
// Selected Task channel interfaces (selected by integer from array defined by the task) can be connected to // Specification of destination scheduled tasks using reference
// Channels (referenced by name string(s)) // to schedule and task configuration configuration names. Mapping
// of integer denoted data outputs to destination schduled task
object {
[int ma-schedule-channel-interface-selection<0..*>;] // default: all
[string ma-schedule-channel-names<0..*>];
} ma-sched-channels-obj;
// Selected Task outputs to onward tasks (selected by integer from an output array defined by the task) can be sent to
// Task Configurations (referenced by name string(s))
object { object {
[int ma-schedule-task-output-selection<0..*>;] // default: all [string ma-schedule-task-destination-schedule-name];
[string ma-schedule-task-downstream-task-configuration-names<0..*>]; [string ma-schedule-task-destination-task-configuration-name];
} ma-sched-downstream-tasks-obj; [int ma-schedule-task-output-selection<0..*>;] // default: all
} ma-sched-destination-tasks-obj;
Example: A measurement task has two defined inter-task outputs, one Example: A measurement task has two defined inter-task outputs, one
for routine measurement results and one for errors during the task for routine measurement results and one for errors during the task
execution. These are defined as available outputs by the task and execution. These are defined as available outputs by the task and
are denoted by the integers 1 & 2. In this example, both outputs are denoted by the integers 1 & 2. In this example, both outputs
are sent to the same reporting task called "Hourly reporting are sent to the same reporting task called "Hourly reporting Task"
Task". This is done by creating a ma-sched-send-to-tasks-obj with that is excuted from the "Hourly Schedule" schedule. This is done
the output selection as [1,2] and the downstream task by creating a ma-sched-destination-tasks-obj with the output
configuration names as ["Hourly Reporting Task"]. selection as [1,2] and the destination task configuration name as
["Hourly Reporting Task"] and the destination schedule name as
"Hourly Schedule".
Measurement Task Measurement Task
Output 1 -------------+--------------> "Hourly Reporting Task" Output 1 -----+----> "Hourly Schedule":"Hourly Reporting Task"
Output 2 ------------/ Output 2 ----/
3.9. Channels 3.7.2. Channels
A Channel defines a bi-directional communication channel between the A Channel defines a bi-directional communication channel between the
MA and a Controller or Collector. Multiple Channels can be defined MA and a Controller or Collector. Multiple Channels can be defined
to enable results to be split or duplicated across different to enable results to be split or duplicated across different
Collectors. Collectors.
Each Channel contains the details of the remote endpoint (including Each Channel contains the details of the remote endpoint (including
location and security credential information such as the location and security credential information such as the
certificate). The timing of when to communicate over a Channel is certificate). The timing of when to communicate over a Channel is
specified within the Schedule. The certificate can be the digital specified within the Schedule. The certificate can be the digital
certificate associated to the FQDN in the URL or it can be the 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 of the Certification Authority that was used to issue the
certificate for the FQDN (Fully Qualified Domain Name) of the target certificate for the FQDN (Fully Qualified Domain Name) of the target
URL (which will be retrieved later on using a communication protocol URL (which will be retrieved later on using a communication protocol
such as TLS). In order to establish a secure channel, the MA will such as TLS). In order to establish a secure channel, the MA will
use it's own security credentials (in the Configuration Information) use it's own security credentials (in the Configuration Information)
and the given credentials for the individual Channel end-point. and the given credentials for the individual Channel end-point.
As with theTask Configurations, each Channel is also given a local As with theTask Configurations, each Channel is also given a text
short name by which it can be referenced from a Schedule. name by which it can be referenced from a Task Configuration.
Although the same in terms of information, Channels used for Although the same in terms of information, Channels used for
communication with the Controller are refered to as Control Channels communication with the Controller are refered to as Control Channels
whereas Channels to Collectors are refered to as Report Channels. whereas Channels to Collectors are refered to as Report Channels.
Hence Control Channels will be referenced from within the Control Hence Control Channels will be referenced from Control Tasks executed
Schedule, whereas Report Channels will be referenced from within the by a Control Schedule, whereas Report Channels will be referenced
Instruction Schedule. from within Reporting Tasks executed by an Instruction Schedule.
Multiple interfaces are also supported. For example the Controller Multiple interfaces are also supported. For example the Controller
could choose to receive some results over GPRS. This is especially could choose to receive some results over GPRS. This is especially
useful when such results indicate the loss of connectivity on a useful when such results indicate the loss of connectivity on a
different network interface. different network interface.
Example: A Channel using for reporting results may specify that Example: A Channel using for reporting results may specify that
results are to be sent to the URL (https://collector.foo.org/ results are to be sent to the URL (https://collector.foo.org/
report/), using the appropriate digital certificate to establish a report/), using the appropriate digital certificate to establish a
secure channel.. secure channel..
// Channel object with name string allowing reference from Schedule. Contains channel endpoint target URL and security // Channel object with name string allowing reference from Schedule.
// credentials to establish secure channel. Optionally allows interface specification (by interface name string reference) // Contains channel endpoint target URL and security credentials
// and connection when no data is pending for transfer // to establish secure channel. Optionally allows interface
// specification (by interface name string reference)
// and connection when no data is pending for transfer
object { object {
string ma-channel-name; string ma-channel-name;
url ma-channel-target; url ma-channel-target;
credentials ma-channel-credentials; credentials ma-channel-credentials;
[string ma-channel-interface-name;] [string ma-channel-interface-name;]
} ma-channel-obj; } ma-channel-obj;
3.10. Task Configurations 3.7.3. Task Configurations
Conceptually each Task Configuration defines the parameters of a Task Conceptually each Task Configuration defines the parameters of a Task
that the Measurement Agent (MA) may perform at some point in time. 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 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 particular time (this is done by a Schedule). Tasks can be
Measurement Tasks (i.e. those Tasks actually performing some type of Measurement Tasks (i.e. those Tasks actually performing some type of
passive or active measurement) or any other scheduled activity passive or active measurement) or any other scheduled activity
performed by the MA such as transferring information to or from the performed by the MA such as transferring information to or from the
Controller and Collectors. Other examples of Tasks may include data Controller and Collectors. Other examples of Tasks may include data
manipulation or processing Tasks conducted on the MA. manipulation or processing Tasks conducted on the MA.
A Measurement Task Configuration is the same in information terms to A Measurement Task Configuration is the same in information terms to
any other Task Configuration. Both measurement and non-measurement any other Task Configuration. Both measurement and non-measurement
Tasks have a registry entry and specified role to enable the MA to Tasks have a registry entry to enable the MA to uniquely identify the
uniquely identify the Task it should execute and retrieve the schema Task it should execute and retrieve the schema for any parameters
for any parameters that may be passed to the Task. This registry that may be passed to the Task. This registry entry is specified as
entry is specified as a URI and can therefore bye used to identify a URI and can therefore be used to identify the Task within a
the Task within a namespace or point to a web or local file location namespace or point to a web or local file location for the Task
for the Task information. As mentioned previously this entry may be information. As mentioned previously this entry may be used to
used to identify the Measurement Task in a public namespace identify the Measurement Task in a public namespace
[I-D.bagnulo-ippm-new-registry] . [I-D.bagnulo-ippm-new-registry] .
Example: A Measurement Task Configuration may configure a single Example: A Measurement Task Configuration may configure a single
Measurement Task for measuring UDP latency. The Measurement Task Measurement Task for measuring UDP latency. The Measurement Task
Configuration could define the destination port and address for Configuration could define the destination port and address for
the measurement as well as the duration, internal packet timing the measurement as well as the duration, internal packet timing
strategy and other parameters (for example a stream for one hour strategy and other parameters (for example a stream for one hour
and sending one packet every 500 ms). It may also define the and sending one packet every 500 ms). It may also define the
output type and possible parameters (for example the output type output type and possible parameters (for example the output type
can be the 95th percentile mean) where the measurement task can be the 95th percentile mean) where the measurement task
accepts such parameters. It does NOT define when the task starts accepts such parameters. It does not define when the task starts
(this is defined by the Schedule element), so it does not by (this is defined by the Schedule element), so it does not by
itself instruct the MA to actually perform this Measurement Task. itself instruct the MA to actually perform this Measurement Task.
The Task Configuration will include a local short name for reference The Task Configuration will include a local short name for reference
by a Schedule. Task Configurations will also contain a registry by a Schedule. Task Configurations will also contain a registry
entry as described above. In addition the Task can be configured entry as described above. In addition the Task can be configured
through a set of configuration Options. The nature and number of through a set of configuration Options. The nature and number of
these Options will depend upon the Task and will be resolved through these Options will depend upon the Task and will be resolved through
the registry parameter. These options are expressed as name-value the registry parameter. These options are expressed as name-value
pairs although the 'value' may be a structured object instead of a pairs although the 'value' may be a structured object instead of a
simple string or numeric value. The implementation of these name- simple string or numeric value. The implementation of these name-
value pairs will vary between data models such as JSON, XML or TR- value pairs will vary between data models such as JSON, XML or TR-
069. 069.
A parameter that may be present for Reporting Tasks is whether to A parameter that must be present for Reporting Tasks is the Channel
report if there is no measurement result data pending to be reference specifying how to communicate with a Collector. This is
transferred to the Collector. In addtion many tasks will also take included in the task options and will have a value that matches a
channel name that has been defined in the Instruction. Similarly
Control Tasks will have a simialr option with the value set to a
specified Control Channel.
A reporting task might also have a flag parameter to indicate whether
to report if there is no measurement result data pending to be
transferred to the Collector. In addition many tasks will also take
as a parameter which interface to operate over. as a parameter which interface to operate over.
The Task Configuration also contains a suppress-by-default flag that The Task Configuration also contains a suppress-by-default flag that
specifies the behaviour of a default suppress instruction (that does specifies the behaviour of a default suppress instruction (that does
not list explicit tasks or schedules). If this flag is set to FALSE 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 then the Task will not be suppressed. It should be noted that
Controller Tasks are not subject to the suppression instruction and Controller Tasks are not subject to the suppression instruction and
therefore this flag will be ignored in such cases. therefore this flag will be ignored in such cases.
In addition the Task Configuration may optionally also be given a In addition the Task Configuration may optionally also be given a
Measurement Cycle ID. The purpose of this ID is to easily identify a Measurement Cycle ID. The purpose of this ID is to easily identify a
set of measurement results that have been produced by Measurement set of measurement results that have been produced by Measurement
Tasks with comparable Options. This ID could be manually incremented Tasks with comparable Options. This ID could be manually incremented
or otherwise changed when an Option change is implemented which could or otherwise changed when an Option change is implemented which could
mean that two sets of results should not be directly compared. 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 // Task Configuration object with string name to allow reference
// specification of the Task. // from Schedule. Contains URI to link to registry or local
// Options allow the configuration of Task parameters (in the form of name-value pairs) // specification of the Task. Options allow the configuration
// of Task parameters (in the form of name-value pairs)
object { object {
string ma-task-name; string ma-task-name;
uri ma-task-registry-entry; uri ma-task-registry-entry;
string ma-role; [name-value-pair ma-task-options<0..*>];
name-value-pair ma-task-options<0..*>; [boolean ma-task-suppress-by-default;] // default: TRUE
[boolean ma-task-suppress-by-default;] // default: TRUE [string ma-task-cycle-id;]
[string ma-task-cycle-id;] } ma-task-obj;
} ma-task-obj;
3.11. Timing Information 3.7.4. Timing Information
The Timing information object used throughout the information models The Timing information object used throughout the information models
can take one of five different forms: can take one of five different forms:
1. Periodic. Specifies a start, end and interval time in 1. Periodic. Specifies a start, end and interval time in
milliseconds milliseconds
2. Calendar: Specifies a calendar based pattern - e.g. 22 minutes 2. Calendar: Specifies a calendar based pattern - e.g. 22 minutes
past each hour of the day on weekdays past each hour of the day on weekdays
skipping to change at page 24, line 27 skipping to change at page 24, line 48
This randomness parameter defines a uniform interval in milliseconds This randomness parameter defines a uniform interval in milliseconds
over which the start of the task is delayed from the starting times over which the start of the task is delayed from the starting times
specified by the timing object. specified by the timing object.
Both the Periodic and Calendar timing objects allow for a series of Both the Periodic and Calendar timing objects allow for a series of
tasks to be executed. While both have an optional end time, it is tasks to be executed. While both have an optional end time, it is
best practice to always configure an end time and refresh the best practice to always configure an end time and refresh the
information periodically to ensure that lost MAs do not continue information periodically to ensure that lost MAs do not continue
their tasks forever. their tasks forever.
Starup timing is only excuted on device startup - not when a new
Instruction is transferred to the MA. If scheduled task execution is
desired both on the transfer of the Instruction and on device restart
then both the Immediate and Starup timing needs to be used in
conjunction.
The datetime format used for all elements in the information model The datetime format used for all elements in the information model
MUST conform to RFC 3339 [RFC3339] and ISO8601. MUST conform to RFC 3339 [RFC3339].
// Main Timing object with name string to allow reference by Schedule // Main Timing object with name string to allow reference by Schedule
// Must be specialised by one of the Timing options. // Must be specialised by one of the Timing options.
// Includes optional uniform random spread in ms from start time given by Timing specialisation // Includes optional uniform random spread in ms from start time
// given by Timing specialisation
object { object {
[string ma-timing-name;] [string ma-timing-name;]
union { union {
ma-periodic-obj ma-timing-periodic; ma-periodic-obj ma-timing-periodic;
ma-calendar-obj ma-timing-calendar; ma-calendar-obj ma-timing-calendar;
ma-one-off-obj ma-timing-one-off; ma-one-off-obj ma-timing-one-off;
ma-immediate-obj ma-timing-immediate; ma-immediate-obj ma-timing-immediate;
ma-startup-obj ma-timing-startup; ma-startup-obj ma-timing-startup;
} }
[int ma-timing-random-spread;] // milliseconds [int ma-timing-random-spread;] // milliseconds
} ma-timing-obj; } ma-timing-obj;
3.11.1. Periodic Timing 3.7.4.1. Periodic Timing
Information model elements: Information model elements:
// Timing specialisation to run a series of Tasks repeated at set intervals // Timing specialisation to run a series of Tasks repeated at
// set intervals
object { object {
[datetime ma-periodic start;] // default: immediate [datetime ma-periodic start;] // default: immediate
[datetime ma-periodic-end;] // default: indefinite [datetime ma-periodic-end;] // default: indefinite
int ma-periodic-interval; // milliseconds int ma-periodic-interval; // milliseconds
} ma-periodic-obj; } ma-periodic-obj;
3.11.2. Calendar Timing 3.7.4.2. Calendar Timing
Calendar Timing supports the routine execution of Measurement Tasks Calendar Timing supports the routine execution of Measurement Tasks
at specific times and/or on specific dates. It can support more at specific times and/or on specific dates. It can support more
flexible timing than Periodic Timing since the Measurement Task flexible timing than Periodic Timing since the Measurement Task
execution does not have to be uniformly spaced. For example a execution does not have to be uniformly spaced. For example a
Calendar Timing could support the execution of a Measurement Task Calendar Timing could support the execution of a Measurement Task
every hour between 6pm and midnight on weekdays only. every hour between 6pm and midnight on weekdays only.
Calendar Timing is also required to perform measurements at Calendar Timing is also required to perform measurements at
meaningful instances in relation to network usage (e.g., at peak meaningful instances in relation to network usage (e.g., at peak
skipping to change at page 25, line 37 skipping to change at page 26, line 16
devices that may be in an unknown timezone or roam between different devices that may be in an unknown timezone or roam between different
timezones (but know their own timezone information such as through timezones (but know their own timezone information such as through
the mobile network). the mobile network).
Days of week are define using three character strings "Mon", "Tue", Days of week are define using three character strings "Mon", "Tue",
"Wed", "Thu", "Fri", "Sat", "Sun". "Wed", "Thu", "Fri", "Sat", "Sun".
If a day of the month is specified that does not exist in the month If a day of the month is specified that does not exist in the month
(e.g. 29 in Feburary) then those values are ignored. (e.g. 29 in Feburary) then those values are ignored.
The calendar elements within the Calendar Timing do not have defaults
in order to avoid accidental high-frequency execution of Tasks. If
all possible values for an element are desired then the wildcard * is
used.
Information model elements: Information model elements:
// Timing specialisation to run repeated Tasks at specific times and/or days // Timing specialisation to run repeated Tasks at specific
// times and/or days
object { object {
[datetime ma-calendar-start;] // default: immediate [datetime ma-calendar-start;] // default: immediate
[datetime ma-calendar-end;] // default: indefinite [datetime ma-calendar-end;] // default: indefinite
[int ma-calendar-months<0..*>;] // default: 1-12 [int ma-calendar-months<0..*>;] // values: 1-12,*
[days ma-calendar-days-of-week<0..*>;] // default: all [days ma-calendar-days-of-week<0..*>;]
[int ma-calendar-days-of-month<0..*>;] // default 1-31 // values: "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun",*
[int ma-calendar-hours<0..*>;] // default: 0-23 [int ma-calendar-days-of-month<0..*>;] // values 1-31,*
[int ma-calendar-minutes<0..*>;] // default: 0-59 [int ma-calendar-hours<0..*>;] // values: 0-23,*
[int ma-calendar-seconds<0..*>;] // default: 0-59 [int ma-calendar-minutes<0..*>;] // values: 0-59,*
[int ma-calendar-timezone-offset;] [int ma-calendar-seconds<0..*>;] // values: 0-59,*
// default: system timezone offset [int ma-calendar-timezone-offset;]
} ma-calendar-obj; // default: system timezone offset
3.11.3. One-Off Timing } ma-calendar-obj;
3.7.4.3. One-Off Timing
Information model elements: Information model elements:
// Timing specialisation to run once at a specified time/date // Timing specialisation to run once at a specified time/date
object { object {
datetime ma-one-off-time; datetime ma-one-off-time;
} ma-one-off-obj; } ma-one-off-obj;
3.11.4. Immediate Timing 3.7.4.4. Immediate Timing
The immediate timing object has no further information elements. The The immediate timing object has no further information elements. The
measurement or report is simply to be done as soon as possible. measurement or report is simply to be done as soon as possible.
// Timing specialisation to run immediately // Timing specialisation to run immediately
object { object {
// empty // empty
} ma-immediate-obj; } ma-immediate-obj;
3.11.5. Startup Timing 3.7.4.5. Startup Timing
The immediate timing object has no further information elements. The The immediate timing object has no further information elements. The
measurement or report is simply done at MA initiation. measurement or report is simply done at MA initiation.
// Timing specialisation to run at MA startup // Timing specialisation to run at MA startup
object { object {
// empty // empty
} ma-startup-obj; } ma-startup-obj;
skipping to change at page 27, line 6 skipping to change at page 27, line 45
This Information Model deals with information about the control and This Information Model deals with information about the control and
reporting of the Measurement Agent. There are broadly two security reporting of the Measurement Agent. There are broadly two security
considerations for such an Information Model. Firstly the considerations for such an Information Model. Firstly the
Information Model has to be sufficient to establish secure Information Model has to be sufficient to establish secure
communication channels to the Controller and Collector such that communication channels to the Controller and Collector such that
other information can be sent and received securely. Additionally, other information can be sent and received securely. Additionally,
any mechanisms that the Network Operator or other device any mechanisms that the Network Operator or other device
administrator employs to pre-configure the MA must also be secure to administrator employs to pre-configure the MA must also be secure to
protect unauthorized parties from modifying pre-configuration protect unauthorized parties from modifying pre-configuration
information. The second consideration is that no mandated information. These mechanisms are important to ensure that the MA
information items should pose a risk to confidentiality or privacy cannot be hijacked, for example to particpate in a DDoS attack.
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 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.
The Information Model should support wherever relevant, all the
security and privacy requirements associated with the LMAP Framework.
6. 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.
7. References
7.1. Normative References
[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 (work in progress), January 2014.
[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. 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 (work in progress), July
2013.
[RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between
Information Models and Data Models", RFC 3444, January
2003.
Appendix A. JSON Data Model Example
In order to give an example of data in the Information Model we need 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 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 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 Control and Report Protocols. The example is broken down into a
number of different steps that might adhere to the steps within a number of different steps that might adhere to the steps within a
Control and Report Protocol: Control and Report Protocol:
1. Pre-configuration. 1. Pre-configuration.
skipping to change at page 28, line 5 skipping to change at page 30, line 5
4. Instruction 4. Instruction
5. Report 5. Report
6. Suppression 6. Suppression
While the pre-configuration is not delivered as part of the Control 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 Protocol, the same JSON data model is used for consistency and to aid
the reader. the reader.
// Pre-Configuration //Pre-configuration
{ {
"ma-config": { "ma-config": {
"ma-agent-id": "550e8400-e29b-41d4-a716-446655440000", "ma-agent-id": "550e8400-e29b-41d4-a716-446655440000",
"ma-control-tasks": [ "ma-control-tasks": [
{ {
"ma-task-name": "Controller configuration", "ma-task-name": "Controller configuration",
"ma-task-registry-entry": "urn:ietf:lmap:control:http_controller_configuration" "ma-task-registry-entry":
} "urn:ietf:lmap:control:http_controller_configuration",
] "ma-task-options": [{"name": "channel",
"ma-control-channels": [ "value": "Controller channel"}]
{
"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-channels": [
{
"ma-schedule-channel-interface-selection": [1],
"ma-schedule-task-source-channel-names": ["Controller channel"]
}
]
}
} }
"ma-schedule-timing": { ],
"ma-timing-name": "startup plus up to one hour", "ma-control-channels": [
"ma-timing-startup": { {
"ma-channel-name": "Controller channel",
"ma-channel-target": "http://www.example.com/lmap/controller",
"ma-channel-credientials": { }
}
],
"ma-control-schedules": [
{
"ma-schedule-name": "pre-configured schedule",
"ma-schedule-tasks": {
"ma-schedule-task-name": "Controller configuration",
},
"ma-schedule-timing": {
"ma-timing-name": "startup plus up to one hour",
"ma-timing-startup": {
},
"ma-timing-random-spread": "3600000"
} }
"ma-timing-random-spread": "3600000"
} }
} ],
] "ma-credentials": { }
"ma-credentials": { } // structure of certificate ommitted for brevity }
} }
}
Given the pre-configuration information the MA is able to contact the Given the pre-configuration information the MA is able to contact the
Controller and receive an updated/expanded Configuration. In this Controller and receive an updated/expanded Configuration. In this
example additional Control Protocol tasks to post Status and example additional Control Protocol tasks to post Status and
Capabilities to the Controller and fetch the Instruction are added as Capabilities to the Controller and fetch the Instruction are added as
well as moving the schedule timing for contacting the Controller to well as moving the schedule timing for contacting the Controller to
hourly. hourly.
// Configuration // Configuration
{ {
"ma-config": { "ma-config": {
"ma-agent-id": "550e8400-e29b-41d4-a716-446655440000", "ma-agent-id": "550e8400-e29b-41d4-a716-446655440000",
"ma-control-tasks": [ "ma-control-tasks": [
{ {
"ma-task-name": "Controller configuration", "ma-task-name": "Controller configuration",
"ma-task-registry-entry": "urn:ietf:lmap:control:http_controller_configuration" "ma-task-registry-entry":
}, "urn:ietf:lmap:control:http_controller_configuration",
{ "ma-task-options": [{"name": "channel",
"ma-task-name": "Controller status and capabilities", "value": "Controller channel"}]
"ma-task-registry-entry": "urn:ietf:lmap:control:http_controller_status_and_capabilities" },
}, {
{ "ma-task-name": "Controller status and capabilities",
"ma-task-name": "Controller instruction", "ma-task-registry-entry":
"ma-task-registry-entry": "urn:ietf:lmap:control:http_controller_instruction" "urn:ietf:lmap:control:http_control_status_and_capabilities",
} "ma-task-options": [{"name": "channel",
] "value": "Controller channel"}]
"ma-control-channels": [ },
{ {
"ma-channel-name": "Controller instruction", "ma-task-name": "Controller instruction",
"ma-channel-target": "http://www.example.com/lmap/controller", "ma-task-registry-entry":
"ma-channel-credientials": { } // structure of certificate ommitted for brevity "urn:ietf:lmap:control:http_controller_instruction",
} "ma-task-options": [{"name": "channel",
] "value": "Controller channel"}]
"ma-control-schedules": [ }
{ ],
"ma-schedule-name": "Controller schedule", "ma-control-channels": [
"ma-schedule-tasks": [ {
{ "ma-channel-name": "Controller channel",
"ma-schedule-task-name": "Controller configuration", "ma-channel-target": "http://www.example.com/lmap/controller",
"ma-schedule-channels": [ "ma-channel-credientials": { }
{ }
"ma-schedule-channel-interface-selection": [1], ],
"ma-schedule-task-source-channel-names": ["Controller channel"] "ma-control-schedules": [
} {
] "ma-schedule-name": "Controller schedule",
}, "ma-schedule-tasks": [
{ {
"ma-schedule-task-name": "Controller status and capabilities", "ma-schedule-task-name": "Controller configuration",
"ma-schedule-channels": [ },
{ {
"ma-schedule-channel-interface-selection": [1], "ma-schedule-task-name":
"ma-schedule-task-source-channel-names": ["Controller channel"] "Controller status and capabilities",
}
] },
}, {
{ "ma-schedule-task-name": "Controller instruction",
"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-schedule-timing": {
} "ma-timing-name": "hourly randomly",
] "ma-timing-calendar": {
"ma-credentials": { } // structure of certificate ommitted for brevity "ma-calendar-minutes": ["00"],
} "ma-calendar-seconds": ["00"]
} },
"ma-timing-random-spread": "3600000"
}
}
],
"ma-credentials": { }
}
}
The above configuration now contacts the Controller randomnly within The above configuration now contacts the Controller randomnly within
each hour. The following is an example of the Status and each hour. The following is an example of the Status and
Capabilities information that is transferred from the MA to the Capabilities information that is transferred from the MA to the
Controller. Controller.
// Status and Capabilities // Status and Capabilities
{ {
ma-status-and-capabilities { "ma-status-and-capabilities": {
"ma-agent-id": "550e8400-e29b-41d4-a716-446655440000", "ma-agent-id": "550e8400-e29b-41d4-a716-446655440000",
"ma-device-id": "urn:dev:mac:0024befffe804ff1" "ma-device-id": "urn:dev:mac:0024befffe804ff1",
"ma-hardware": "mfr-home-gateway-v10" "ma-hardware": "mfr-home-gateway-v10",
"ma-firmware": "25637748-rev2a" "ma-firmware": "25637748-rev2a",
"ma-version": "ispa-v1.01" "ma-version": "ispa-v1.01",
"ma-interfaces: [ "ma-interfaces": [
{ {
"ma-interface-name": "broadband", "ma-interface-name": "broadband",
"ma-interface-type": "PPPoE" "ma-interface-type": "PPPoE"
} }
] ],
"ma-last-measurement: "", "ma-last-task": "",
"ma-last-report: "", "ma-last-report": "",
"ma-last-instruction: "", "ma-last-instruction": "",
"ma-last-configuration: "2014-06-08T22:47:31+00:00", "ma-last-configuration": "2014-06-08T22:47:31+00:00",
"ma-supported-tasks: [ "ma-supported-tasks": [
{ {
"ma-task-name": "Controller configuration", "ma-task-name": "Controller configuration",
"ma-task-registry": "urn:ietf:lmap:control:http_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 status and capabilities",
}, "ma-task-registry":
{ "urn:ietf:lmap:control:http_control_status_and_capabilities"
"ma-task-name": "Controller instruction", },
"ma-task-registry": "urn:ietf:lmap:control:http_controller_instruction" {
}, "ma-task-name": "Controller instruction",
{ "ma-task-registry":
"ma-task-name": "Report", "urn:ietf:lmap:control:http_controller_instruction"
"ma-task-registry": "urn:ietf:lmap:report:http_report" },
}, {
{ "ma-task-name": "Report",
"ma-task-name": "UDP Latency", "ma-task-registry": "urn:ietf:lmap:report:http_report"
"ma-task-registry": "urn:ietf:ippm:measurement:UDPLatency-Poisson-XthPercentileMean" },
} {
] "ma-task-name": "UDP Latency",
"ma-task-registry":
"urn:ietf:ippm:measurement:UDPLatency-Poisson-XthPercMean"
}
]
}
} }
}
After fetching the status and capabilties the Controller issues and After fetching the status and capabilties the Controller issues and
Instruction to the MA to perform a single UDP latency measurement Instruction to the MA to perform a single UDP latency measurement
task 4 times a day and to report the results immediately. task 4 times a day and to report the results immediately.
// Instruction // Instruction
{ {
"ma-instruction": { "ma-instruction": {
"ma-instruction-tasks": [ "ma-instruction-tasks": [
{ {
"ma-task-name": "UDP Latency", "ma-task-name": "UDP Latency",
"ma-task-registry-entry": "urn:ietf:ippm:measurement:UDPLatency-Poisson-XthPercentileMean", "ma-task-registry-entry":
"urn:ietf:ippm:measurement:UDPLatency-Poisson-XthPercMean",
"ma-task-options": [ "ma-task-options": [
{"name": "X", "value": "99"}, {"name": "X", "value": "99"},
{"name":"rate", "value": "5"}, {"name":"rate", "value": "5"},
{"name":"duration", "value": "30.000"}, {"name":"duration", "value": "30.000"},
{"name":"interface", "value": "broadband"}, {"name":"interface", "value": "broadband"},
{"name":"destination-ip", "value": {"version":"ipv4", "ip-address":"192.168.2.54"}}, {"name":"destination-ip",
"value": {"version":"ipv4", "ip-address":"192.168.2.54"}},
{"name":"destination-port", "value": "50000"}, {"name":"destination-port", "value": "50000"},
{"name":"source-port", "value": "50000"} {"name":"source-port", "value": "50000"}
], ],
"ma-task-suppress-by-default": "TRUE" "ma-task-suppress-by-default": "TRUE"
}, },
{ {
"ma-task-name": "Report", "ma-task-name": "Report",
"ma-task-registry-entry": "urn:ietf:lmap:report:http_report", "ma-task-registry-entry": "urn:ietf:lmap:report:http_report",
"ma-task-options": [ "ma-task-options": [
{"name": "report-with-no-data", "value": "FALSE"} {"name": "report-with-no-data", "value": "FALSE"},
{"name": "channel", "value": "Collector A"]}
], ],
"ma-task-suppress-by-default": "FALSE" "ma-task-suppress-by-default": "FALSE"
} }
] ],
"ma-report-channels": [ "ma-report-channels": [
{ {
"ma-channel-name": "Collector A", "ma-channel-name": "Collector A",
"ma-channel-target": "http://www.example2.com/lmap/collector", "ma-channel-target": "http://www.example2.com/lmap/collector",
"ma-channel-credientials": { } // structure of certificate ommitted for brevity "ma-channel-credientials": { }
} }
] ],
"ma-instruction-schedules": [ "ma-instruction-schedules": [
{ {
"ma-schedule-name": "4 times daily test UDP latency and report", "ma-schedule-name": "4 times daily test UDP latency and report",
"ma-schedule-tasks": { "ma-schedule-tasks": [
{ {
"ma-schedule-task-name": "UDP Latency", "ma-schedule-task-name": "UDP Latency",
"ma-schedule-downstream-tasks": [ "ma-schedule-destination-tasks": [
{ {
"ma-schedule-task-output-selection": [1], "ma-schedule-task-output-selection": [1],
"ma-schedule-task-downstream-task-configuration-names": "Report" "ma-schedule-task-destination-schedule-name":
"4 times daily test UDP latency and report",
"ma-schedule-task-destination-task-configuration-names":
"Report"
} }
] ]
}, },
{ {
"ma-schedule-task-name": "Report", "ma-schedule-task-name": "Report",
"ma-schedule-channels": [
{
"ma-schedule-channel-interface-selection": [1],
"ma-schedule-channel-names": "Collector A"
}
]
} }
} ],
"ma-schedule-timing": { "ma-schedule-timing": {
"ma-timing-name": "once every 6 hours", "ma-timing-name": "once every 6 hours",
"ma-timing-calendar": { "ma-timing-calendar": {
"ma-calendar-hours": ["00", "06", "12", "18"], "ma-calendar-hours": ["00", "06", "12", "18"],
"ma-calendar-minutes": ["00"], "ma-calendar-minutes": ["00"],
"ma-calendar-seconds": ["00"] "ma-calendar-seconds": ["00"]
} },
"ma-timing-random-spread": "21600000" "ma-timing-random-spread": "21600000"
} }
} }
] ]
} }
} }
The report task in the Instruction is executed immediately after the The report task in the Instruction is executed immediately after the
UDP test and transfers the following data to the Collector. UDP test and transfers the following data to the Collector.
// Report // Report
{ {
ma-report: { "ma-report": {
"ma-report-date": "2014-06-09T02:30:45+00:00", "ma-report-date": "2014-06-09T02:30:45+00:00",
"ma-report-agent-id": "550e8400-e29b-41d4-a716-446655440000", "ma-report-agent-id": "550e8400-e29b-41d4-a716-446655440000",
"ma-report-tasks": [ "ma-report-tasks": [
"ma-report-task-config": { {
"ma-task-name": "UDP Latency", "ma-report-task-name": "UDP Latency",
"ma-task-registry-entry": "urn:ietf:ippm:measurement:UDPLatency-Poisson-XthPercentileMean", "ma-report-task-registry-entry":
"ma-task-options": [ "urn:ietf:ippm:measurement:UDPLatency-Poisson-XthPercMean",
{"name": "X", "value": "99"}, "ma-report-scheduled-task-options": [
{"name":"rate", "value": "5"}, {"name": "X", "value": "99"},
{"name":"duration", "value": "30.000"}, {"name":"rate", "value": "5"},
{"name":"interface", "value": "broadband"}, {"name":"duration", "value": "30.000"},
{"name":"destination-ip", "value": {"version":"ipv4", "ip-address":"192.168.2.54"}}, {"name":"interface", "value": "broadband"},
{"name":"destination-port", "value": "50000"}, {"name":"destination-ip",
{"name":"source-port", "value": "50000"} "value": {"version":"ipv4", "ip-address":"192.168.2.54"}},
] {"name":"destination-port", "value": "50000"},
}, {"name":"source-port", "value": "50000"}
"ma-report-task-column-labels": ["start-time", "conflicting-tasks", "cross-traffic", "mean", "min", "max"], ],
"ma-report-task-rows": [{"2014-06-09T02:30:10+00:00", "", "0", "20.13", "18.3", "24.1"}] "ma-report-task-column-labels":
["start-time", "conflicting-tasks", "cross-traffic",
"mean", "min", "max"],
"ma-report-task-rows":
["2014-06-09T02:30:10+00:00", "", "0",
"20.13", "18.3", "24.1"]
}
] ]
} }
} }
The Controller decides that there is a problem with the UDP L:atency The Controller decides that there is a problem with the UDP L:atency
test and issues a Suppression Instruction. Since the task is marked test and issues a Suppression Instruction. Since the task is marked
as suppressable by default, simply turning on suppression will stop as suppressable by default, simply turning on suppression will stop
the task being executed in future. the task being executed in future.
// Suppression // Suppression
{ {
"ma-instruction": { "ma-instruction": {
"ma-suppression": { "ma-suppression": {
"ma-suppression-enabled": "TRUE" "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
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.
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 (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 (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 Authors' Addresses
Trevor Burbridge Trevor Burbridge
BT BT
Adastral Park, Martlesham Heath Adastral Park, Martlesham Heath
Ipswich IP5 3RE Ipswich IP5 3RE
United Kingdom United Kingdom
Email: trevor.burbridge@bt.com Email: trevor.burbridge@bt.com
 End of changes. 135 change blocks. 
600 lines changed or deleted 645 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/