draft-ietf-lmap-information-model-04.txt   draft-ietf-lmap-information-model-05.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: September 6, 2015 M. Bagnulo Expires: October 12, 2015 M. Bagnulo
Universidad Carlos III de Madrid Universidad Carlos III de Madrid
J. Schoenwaelder J. Schoenwaelder
Jacobs University Bremen Jacobs University Bremen
March 5, 2015 April 10, 2015
Information Model for Large-Scale Measurement Platforms (LMAP) Information Model for Large-Scale Measurement Platforms (LMAP)
draft-ietf-lmap-information-model-04 draft-ietf-lmap-information-model-05
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 September 6, 2015. This Internet-Draft will expire on October 12, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2015 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 . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Notation . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Notation . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. LMAP Information Model . . . . . . . . . . . . . . . . . . . 4 3. LMAP Information Model . . . . . . . . . . . . . . . . . . . 4
3.1. Pre-Configuration Information . . . . . . . . . . . . . . 7 3.1. Pre-Configuration Information . . . . . . . . . . . . . . 8
3.1.1. Definition of ma-preconfig-obj . . . . . . . . . . . 9
3.2. Configuration Information . . . . . . . . . . . . . . . . 9 3.2. Configuration Information . . . . . . . . . . . . . . . . 9
3.3. Instruction Information . . . . . . . . . . . . . . . . . 10 3.2.1. Definition of ma-config-obj . . . . . . . . . . . . . 11
3.4. Logging Information . . . . . . . . . . . . . . . . . . . 13 3.3. Instruction Information . . . . . . . . . . . . . . . . . 12
3.5. Capability and Status Information . . . . . . . . . . . . 15 3.3.1. Definition of ma-instruction-obj . . . . . . . . . . 14
3.6. Reporting Information . . . . . . . . . . . . . . . . . . 16 3.3.2. Definition of ma-suppression-obj . . . . . . . . . . 14
3.7. Common Objects . . . . . . . . . . . . . . . . . . . . . 19 3.4. Logging Information . . . . . . . . . . . . . . . . . . . 15
3.7.1. Schedules . . . . . . . . . . . . . . . . . . . . . . 19 3.4.1. Definition of ma-log-obj . . . . . . . . . . . . . . 17
3.7.2. Channels . . . . . . . . . . . . . . . . . . . . . . 21 3.5. Capability and Status Information . . . . . . . . . . . . 17
3.7.3. Task Configurations . . . . . . . . . . . . . . . . . 22 3.5.1. Definition of ma-status-obj . . . . . . . . . . . . . 17
3.7.4. Timing Information . . . . . . . . . . . . . . . . . 25 3.5.2. Definition of ma-task-status-obj . . . . . . . . . . 18
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 3.5.3. Definition of ma-interface-obj . . . . . . . . . . . 19
5. Security Considerations . . . . . . . . . . . . . . . . . . . 28 3.6. Reporting Information . . . . . . . . . . . . . . . . . . 20
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 29 3.6.1. Definition of ma-report-obj . . . . . . . . . . . . . 21
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 29 3.6.2. Definition of ma-report-task-obj . . . . . . . . . . 22
7.1. Normative References . . . . . . . . . . . . . . . . . . 29 3.6.3. Definition of ma-report-row-obj . . . . . . . . . . . 23
7.2. Informative References . . . . . . . . . . . . . . . . . 29 3.7. Common Objects: Schedules . . . . . . . . . . . . . . . . 23
Appendix A. JSON Data Model Example . . . . . . . . . . . . . . 30 3.7.1. Definition of ma-schedule-obj . . . . . . . . . . . . 25
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 38 3.7.2. Definition of ma-action-obj . . . . . . . . . . . . . 25
3.7.3. Definition of ma-action-dest-obj . . . . . . . . . . 26
3.8. Common Objects: Channels . . . . . . . . . . . . . . . . 26
3.8.1. Definition of ma-channel-obj . . . . . . . . . . . . 27
3.9. Common Objects: Task Configurations . . . . . . . . . . . 28
3.9.1. Definition of ma-task-obj . . . . . . . . . . . . . . 29
3.9.2. Definition of ma-option-obj . . . . . . . . . . . . . 30
3.10. Common Objects: Timing Information . . . . . . . . . . . 30
3.10.1. Definition of ma-timing-obj . . . . . . . . . . . . 31
3.10.2. Definition of ma-periodic-obj . . . . . . . . . . . 32
3.10.3. Definition of ma-calendar-obj . . . . . . . . . . . 33
3.10.4. Definition of ma-one-off-obj . . . . . . . . . . . . 35
3.10.5. Definition of ma-immediate-obj . . . . . . . . . . . 35
3.10.6. Definition of ma-startup-obj . . . . . . . . . . . . 35
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35
5. Security Considerations . . . . . . . . . . . . . . . . . . . 36
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 36
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 36
7.1. Normative References . . . . . . . . . . . . . . . . . . 36
7.2. Informative References . . . . . . . . . . . . . . . . . 37
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 37
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 6, line 19 skipping to change at page 6, line 41
1. Schedules. A set of Schedules tell the MA to do something. 1. Schedules. A set of Schedules tell the MA to do something.
Without a Schedule no Task (from a measurement to reporting or Without a Schedule no Task (from a measurement to reporting or
communicating with the Controller) is ever executed. Schedules communicating with the Controller) is ever executed. Schedules
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).
Channel object contains the information required for the Each 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. and security details.
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 specifies either a singleton or series
time events. They are used to indicate when Tasks should be of 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 (Task Configuration, Timing) being given a short text each object (Task Configuration, Timing) being given a short text
name that is used by other objects. The objects shown in parenthesis name that is used by other objects. The objects shown in parenthesis
are part of the internal object structure of a Schedule. Channels are part of the internal object structure of a Schedule. Channels
are not shown in the diagram since they are only used as an option by are not shown in the diagram since they are only used as an option by
selected Task Configurations but are similarly referenced using a selected Task Configurations but are similarly referenced using a
short text name. short text name.
Schedule Schedule
|----------> Timing |----------> Timing
|----------> (Scheduled Tasks) |----------> (Scheduled Tasks)
|----------> Task Configuration |----------> Task Configuration
|----------> Destination Tasks |----------> Destination Tasks
It should be clear that the top-level bahaviour of an MA is simply to It should be clear that the top-level behavior 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 measure some aspect of network performance or 1. Measurement Tasks measure some aspect of network performance or
traffic. They may also capture contextual information from the traffic. They may also capture contextual information from the
skipping to change at page 8, line 5 skipping to change at page 8, line 27
device identifier and device security credentials). 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 from where configuration information can be initial Controller from where configuration information can be
communicated along with the security information required for the communicated along with the security information required for the
communication including the certificate of the Controller (or the communication including the certificate of the Controller (or the
certificate of the Certification Authority which was used to issue certificate of the Certification Authority which was used to issue
the certificate for the Controller). All this is expressed as a the certificate for the Controller). All this is expressed as a
Channel. While multiple Channels may be provided in the Pre- Channel. While multiple Channels may be provided in the Pre-
Configuration Information they must all be associated with a single Configuration Information they must all be associated with a single
Controller (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
transferred). The timing is given as a Schedule that executes the transferred). 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 and utilises the Channel information. The MA and the Controller and utilises the Channel information. The
Task(s) may take additional parameters in which case a Task Task(s) may take additional parameters in which case a Task
skipping to change at page 8, line 33 skipping to change at page 9, line 8
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 first 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 URI. 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: 3.1.1. Definition of ma-preconfig-obj
// MA pre-configuration minimal information to communicate object {
// initially with Controller [uuid ma-agent-id;]
ma-task-obj ma-control-tasks<1..*>;
ma-channel-obj ma-control-channels<1..*>;
ma-schedule-obj ma-control-schedules<1..*>;
[uri ma-device-id;]
credentials ma-credentials;
} ma-preconfig-obj;
object { The ma-preconfig-obj is essentially a subset of the ma-config-obj
[uuid ma-agent-id;] described below. The ma-preconfig-obj consists of the following
ma-task-obj ma-control-tasks<1..*>; elements:
ma-channel-obj ma-control-channels<1..*>;
ma-schedule-obj ma-control-schedules<1..*>;
[urn ma-device-id;]
credentials ma-credentials;
} ma-config-obj;
The details of the Channel and Schedule objects are described later ma-agent-id: An optional uuid uniquely identifying the
since they are common to several parts of the information model. measurement agent.
ma-control-tasks: A collection of tasks objects.
ma-control-channels: A collection of channel objects.
ma-control-schedules: A collection of scheduling objects.
ma-device-id: An optional identifier for the device.
ma-credentials: The security credentials used by the
measurement agent.
3.2. 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
over-ridden with a specific Controller that is more appropriate to over-ridden with a specific Controller that is more appropriate to
the MA device type, location or characteristics of the network (e.g. the 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 over-ridden 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 may only use a single Schedule, other While some Control protocols may only use a single Schedule, other
protocols may use several Schedules (and related data transfer Tasks) protocols may use several Schedules (and related data transfer Tasks)
to update the Configuration Information, transfer the Instruction to update the Configuration Information, transfer the Instruction
Information, transfer Capability and Status Information and send Information, transfer Capability and Status Information 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
identifies a group of interest to which that MA belongs. For example identifies a group of interest to which that MA belongs. For example
the group could represent an ISP, broadband product, technology, the group could represent an ISP, broadband product, technology,
skipping to change at page 10, line 16 skipping to change at page 10, line 51
While Pre-Configuration Information is persistent upon device reset While Pre-Configuration Information is persistent upon device reset
or power cycle, the persistency of the Configuration Information may or power cycle, the persistency of the Configuration Information may
be device dependent. Some devices may revert back to their pre- be device dependent. Some devices may revert back to their pre-
configuration state upon reboot or factory reset, while other devices configuration state upon reboot or factory reset, while other devices
may store all Configuration and Instruction information in persistent may store all Configuration and Instruction information in persistent
storage. A Controller can check whether an MA has the latest storage. A Controller can check whether an MA has the latest
Configuration and Instruction information by examining the Capability Configuration and Instruction information by examining the Capability
and Status information for the MA. and Status information for the MA.
It should be noted that control shcedules and tasks cannot be It should be noted that control schedules 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 (i.e. within the Configuration information). Any as control tasks (i.e., within the Configuration information). Any
suppress-by-default flag against control tasks will be ignored. suppress-by-default flag against control tasks will be ignored.
Detail of the additional and updated information model elements: 3.2.1. Definition of ma-config-obj
// MA Configuration object {
uuid ma-agent-id;
ma-task-obj ma-control-tasks<1..*>;
ma-channel-obj ma-control-channels<1..*>;
ma-schedule-obj ma-control-schedules<1..*>;
[uri ma-device-id;]
credentials ma-credentials;
[string ma-group-id;]
[boolean ma-report-agent-id;]
[int ma-controller-lost-timeout;]
} ma-config-obj;
object { The ma-config-obj consists of the following elements:
uuid ma-agent-id;
ma-task-obj ma-control-tasks<1..*>; ma-agent-id: A uuid uniquely identifying the measurement
ma-channel-obj ma-control-channels<1..*>; agent.
ma-schedule-obj ma-control-schedules<1..*>;
[urn ma-device-id;] ma-control-tasks: A collection of task objects.
credentials ma-credentials;
[string ma-group-id;] ma-control-channels: A collection of channel objects.
[boolean ma-report-ma-id-flag;]
[int ma-control-channel-failure-threshold;] ma-control-schedules: A collection of scheduling objects.
} ma-config-obj;
ma-device-id: An optional identifier for the device.
ma-credentials: The security credentials used by the
measurement agent.
ma-group-id: An optional identifier of the group of
measurement agents this measurement agent
belongs to.
ma-report-agent-id: An optional flag indicating whether the
identifier (ma-agent-id) should be included
in reports.
ma-controller-lost-timeout: A timer is started after each successful
contact with a controller. When the timer
reaches the controller-lost-timeout, all
schedules will be disabled.
3.3. 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
skipping to change at page 11, line 27 skipping to change at page 12, line 42
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 be used by multiple (reporting) destinations. A single Channel can be used by multiple (reporting)
Task Configurations to transfer data to the same Collector. A single Task Configurations to transfer data to the same Collector. A single
Reporting Task Configuration can also be included in multiple Reporting Task Configuration can also be included in multiple
Schedules. E.g. a single Collector may receive data at three Schedules. E.g., a single Collector may receive data at three
different cycle rates, one Schedule reporting hourly, another different cycle rates, one Schedule reporting hourly, another
reporting daily and a third specifying that results should be sent reporting daily and a third specifying that results should be sent
immediately for on-demand measurement tasks. Alternatively multiple immediately for on-demand measurement tasks. Alternatively multiple
Report Channels can be used to send Measurement Task results to Report Channels can be used to send Measurement Task results to
different Collectors. The details of the Channel element is different Collectors. The details of the Channel element is
described later as it is common to several objects. 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 link Tasks output data to other The Schedule also specifies how to link Tasks output data to other
scheduled Tasks - i.e. sending selected outputs to other Tasks. scheduled Tasks, i.e., sending selected outputs to other Tasks.
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 33 skipping to change at page 13, line 48
individual tasks and individual schedules are listed then only the individual tasks and individual schedules are listed then only the
listed schedules, plus the listed tasks where present in other listed schedules, plus the listed tasks where present in other
schedules, will be suppressed regardless of the suppress-by-default schedules, will be suppressed regardless of the suppress-by-default
flag. flag.
Suppression stops new Tasks from executing. In addition, the Suppression stops new Tasks from executing. In addition, 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
the use of an End time such that the Measurement Suppression will no through the use of an End time such that the Measurement Suppression
longer be in effect beyond this time. The datetime format used for will no longer be in effect beyond this time. The datetime format
all elements in the information model (e.g. the suppression start and used for all elements in the information model (e.g., the suppression
end dates) MUST conform to RFC 3339 [RFC3339]. start and 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: 3.3.1. Definition of ma-instruction-obj
// Instruction to the MA to configure Tasks, Channels, object {
//Schedules and Suppression ma-task-obj ma-instruction-tasks<0..*>;
ma-channel-obj ma-report-channels<0..*>;
ma-schedule-obj ma-instruction-schedules<0..*>;
ma-suppression-obj ma-suppression;
} ma-instruction-obj;
object { An ma-instruction-obj consists of the following elements:
ma-task-obj ma-instruction-tasks<0..*>;
ma-channel-obj ma-report-channels<0..*>;
ma-schedule-obj ma-instruction-schedules<0..*>;
ma-suppression-obj ma-suppression;
} ma-instruction-obj;
// Suppression object to temporarily override new task execution ma-task-obj: A possibly empty collection of task objects.
// in Instructions and optionally stop currently running tasks
object { ma-channel-obj: A possibly empty collection of channel objects.
boolean ma-suppression-enabled;
[boolean ma-suppression-stop-ongoing-tasks;] ma-schedule-obj: A possibly empty collection of schedule objects.
// default: false
[datetime ma-suppression-start;] // default: immediate ma-suppression-obj: A suppression object.
[datetime ma-suppression-end;] // default: indefinite
[string ma-suppression-task-names<0..*>;] 3.3.2. Definition of ma-suppression-obj
// default: all tasks if
// ma-suppression-task-names is empty object {
[string ma-suppression-schedule-names<0..*>;] boolean ma-suppression-enabled;
// default: all schedules if [boolean ma-suppression-stop-running;]
// ma-suppression-schedule-names is empty [datetime ma-suppression-start;]
} ma-suppression-obj; [datetime ma-suppression-end;]
[string ma-suppression-task-names<0..*>;]
[string ma-suppression-schedule-names<0..*>;]
} ma-suppression-obj;
The ma-suppression-obj consists of the following elements:
ma-suppression-enabled: A boolean indicating whether
suppression is enabled or not. The
default value is false.
ma-suppression-stop-running: An optional boolean indicating
whether suppression will stop any
running tasks. The default value for
this boolean is false.
ma-suppression-start: The optional date and time when
suppression starts. The default
value is 'immediate'.
ma-suppression-end: The optional date and time when
suppression ends. The default value
is 'indefinite'.
ma-suppression-task-names: An optional and possibly empty
collection of task names. If not
present, this defaults to all tasks.
ma-suppression-schedule-names: An optional and possibly empty
collection of schedule names. If not
present, this defaults to all
schedules.
3.4. 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 in exactly the same manner as scheduling any information is achieved in exactly the same manner as scheduling any
other Task. We make no distinction between a Measurement Task other Task. We make no distinction between a Measurement Task
conducting an active or passive network measurement and one which conducting an active or passive network measurement and one which
skipping to change at page 14, line 45 skipping to change at page 16, line 41
* "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:
* "Device 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: 3.4.1. Definition of ma-log-obj
// Logging object object {
uuid ma-log-agent-id;
datetime ma-log-event-time;
code ma-log-code;
string ma-log-description;
} ma-log-obj;
object { The ma-log-obj models the generic aspects of a logging object and
uuid ma-log-agent-id; consists of the following elements:
datetime ma-log-event-time;
code ma-log-code; ma-log-agent-id: A uuid uniquely identifying the measurement
string ma-log-description; agent.
} ma-log-obj;
ma-log-event-time: The date and time of the event reported in
the logging object.
ma-log-code: A machine readable code describing the
event.
ma-log-description: A human readable description of the event.
3.5. 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 device interface details Controller. Capabilities include the device interface details
available to Measurement Tasks as well as the set of Measurement available to Measurement Tasks as well as the set of Measurement
Tasks/Roles (specified by a registry entry) that are actually Tasks/Roles (specified by a registry entry) that are actually
installed or available on the MA. Status information includes the installed or available on the MA. Status information includes the
times that operations were last performed such as contacting the times that operations were last performed such as contacting the
Controller or producing Reports. Controller or producing Reports.
MA Status information model elements: 3.5.1. Definition of ma-status-obj
// Main MA Status information object object {
uuid ma-agent-id;
uri ma-device-id;
string ma-hardware;
string ma-firmware;
string ma-version;
ma-interface-obj ma-interfaces<0..*>;
datetime ma-last-started;
[ma-task-status-obj ma-task-status<0..*>;]
} ma-status-obj;
object { The ma-status-obj provides status information about the measurement
uuid ma-agent-id; agent and consists of the following elements:
urn ma-device-id;
string ma-hardware;
string ma-firmware;
string ma-version;
ma-interface-obj ma-interfaces<0..*>;
ma-task-capability-obj ma-supported-tasks<0..*>;
datetime ma-last-started;
[ma-condition-obj ma-conditions<0..*>;]
[ma-task-status-obj ma-task-status<0..*>;]
} ma-status-obj;
// Per-Task status information and conditions
object { ma-agent-id: A uuid uniquely identifying the measurement
string ma-task-name; agent.
string ma-task-role;
uri ma-task-registry;
datetime ma-task-last-invocation;
datetime ma-task-last-successful;
string ma-task-last-successful-message;
datetime ma-task-last-failed;
string ma-task-last-failed-message;
[ma-condition-obj ma-task-conditions<0..*>];
} ma-task-status-obj
// Additional status conditions ma-device-id: A URI identifying the device.
object { ma-hardware: A description of the hardware of the device
int ma-condition-code; the measurement agent is running on.
string ma-condition-text;
} ma-condition-obj
// Interface information ma-firmware: A description of the firmware of the device
the measurement agent is running on.
object { ma-version: The version of the measurement agent.
string ma-interface-name;
string ma-interface-type;
[int ma-interface-speed;] // bps
[string ma-link-layer-address;]
[ip-address ma-interface-ip-addresses<0..*>];
[ip-address ma-interface-gateways<0..*>;]
[ip-address ma-interface-dns-servers<0..*>;]
} ma-interface-obj;
// Supported tasks/roles ma-interfaces: A list of network interfaces available on
the device.
object { ma-last-started: The date and time the measurement agent
string ma-task-name; last started.
string ma-task-role;
uri ma-task-registry; ma-task-status: An optional list of status objects for each
} ma-task-capability-obj; supported task.
3.5.2. Definition of ma-task-status-obj
object {
string ma-task-name;
[uri ma-task-registry-entry;]
[string ma-task-role<0..*>;]
datetime ma-task-last-invocation;
datetime ma-task-last-completion;
int ma-task-last-status;
string ma-task-last-message;
datetime ma-task-last-failed-completion;
int ma-task-last-failed-status;
string ma-task-last-failed-message;
} ma-task-status-obj;
The ma-task-status-obj provides status information about a task and
consists of the following elements:
ma-task-name: A name uniquely identifying a task.
ma-task-registry-entry: An optional URI identifying the
nature of the task.
ma-task-role: An optional and possibly empty list
of roles of a task.
ma-task-last-completion: The date and time of the last
completion of this task.
ma-task-last-status: The status code returned by the last
execution of this task.
ma-task-last-message: The status message produced by the
last execution of this task.
ma-task-last-failed-completion: The date and time of the last failed
completion of this task.
ma-task-last-failed-status: The status code returned by the last
failed execution of this task.
ma-task-last-failed-message: The status message produced by the
last failed execution of this task.
3.5.3. Definition of ma-interface-obj
object {
string ma-interface-name;
string ma-interface-type;
[int ma-interface-speed;]
[string ma-interface-link-layer-address;]
[ip-address ma-interface-ip-addresses<0..*>];
[ip-address ma-interface-gateways<0..*>;]
[ip-address ma-interface-dns-servers<0..*>;]
} ma-interface-obj;
The ma-interface-obj provides status information about network
interfaces and consists of the following elements:
ma-interface-name: A name uniquely identifying a
network interface.
ma-interface-type: The type of the network interface.
ma-interface-speed: An optional indication of the speed
of the interface (measured in bits-
per-second).
ma-interface-link-layer-address: An optional link-layer address of
the interface.
ma-interface-ip-addresses: An optional list of IP addresses
assigned to the interface.
ma-interface-gateways: An optional list of gateways
assigned to the interface.
ma-interface-dns-servers: An optional list of DNS servers
assigned to the interface.
3.6. 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. These Reporting Tasks will be configured to transmit task Collector. These Reporting Tasks will be configured to transmit task
results over a specified Report Channel to a Collector. results over a specified Report Channel to a Collector.
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 generated by a Reporting Task is structured hierarchically The Report generated by a Reporting Task is structured hierarchically
to avoid repetition of report header and Measurement Task to avoid repetition of report header and Measurement Task
Configuration information. The report starts with the timestamp of Configuration information. The report starts with the timestamp of
the report generation on the MA and details about the MA including the report generation on the MA and details about the MA including
the optional Measurement Agent ID and Group ID (controlled by the the optional Measurement Agent ID and Group ID (controlled by the
Configuration Information). Configuration Information).
skipping to change at page 18, line 24 skipping to change at page 21, line 33
well as additional Options specified in the Scheduled Task. The well as additional Options specified in the Scheduled Task. The
Scheduled Task Options are appended to the Task Configuration Options Scheduled Task Options are appended to the Task Configuration Options
in exactly the same order as they were provided to the Task during in exactly the same order as they were provided to the Task during
execution. execution.
The result row data includes 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. considered in the data analysis.
Some Measurement Tasks may optionally include an indication of the Some Measurement Tasks may optionally include an indication of the
cross-traffic although the meaning a definition of cross-traffic is cross-traffic although the definition of cross-traffic is left up to
left up to each individual Measurement Task. Some Measurement Tasks each individual Measurement Task. Some Measurement Tasks may also
may also output other environmental measures in addition to cross- output other environmental measures in addition to cross-traffic such
traffic such as CPU utlilisation or interface speed. as CPU utlilisation or interface speed.
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: 3.6.1. Definition of ma-report-obj
object {
datetime ma-report-date;
[uuid ma-report-agent-id;]
[string ma-report-group-id;]
[ma-report-task-obj ma-report-tasks<0..*>];
} ma-report-obj;
// Main Report object with report header information The ma-report-obj provides the meta-data of a single report and
consists of the following elements:
object { ma-report-date: The date and time when the report was sent
datetime ma-report-date; to a collector.
[uuid ma-report-agent-id;]
[string ma-report-group-id;]
[ma-report-task-obj ma-report-tasks<0..*>];
} ma-report-obj;
// Report task header information
object { ma-report-agent-id: An optional uuid uniquely identifying the
string ma-report-task-name; measurement agent.
[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..*>;
ma-result-row-obj ma-report-task-rows<0..*>;
} ma-report-task-obj;
// Report tasks result rows ma-report-group-id: An optional identifier of the group of
measurement agents this measurement agent
belongs to.
object { ma-report-tasks: An optional and possibly empty list of
datetime ma-report-result-start-time; tasks result objects.
[datetime ma-report-result-end-time;]
string ma-report-result-conflicting-tasks<0..*>;
data ma-report-result-values<0..*>;
} ma-result-row-obj;
3.7. Common Objects 3.6.2. Definition of ma-report-task-obj
3.7.1. Schedules object {
string ma-report-task-name;
[uri ma-report-task-registry-entry;]
[ma-option-obj ma-report-scheduled-task-options<0..*>];
[string ma-report-task-cycle-id;]
string ma-report-task-column-labels<0..*>;
ma-report-row-obj ma-report-task-rows<0..*>;
} ma-report-task-obj;
The ma-report-task-obj provides the meta-data of a result report of a
single task. It consists of the following elements:
ma-report-task-name: A name uniquely identifying the task
that produced the results being
reported.
ma-report-task-registry-entry: An optional URI identifying the type
of task.
ma-report-task-scheduled-task-options: An optional list of task
options provided by the scheduling
object.
ma-report-task-cycle-id: An optional measurement cycle
identifier.
ma-report-task-column-labels: A possibly empty list of column
labels.
ma-report-task-rows: A possibly empty list of result rows.
3.6.3. Definition of ma-report-row-obj
object {
datetime ma-report-result-start-time;
[datetime ma-report-result-end-time;]
string ma-report-result-conflicts<0..*>;
data ma-report-result-values<0..*>;
} ma-report-row-obj;
The ma-report-row-obj represents a result row and consists of the
following elements:
ma-report-result-start-time: The date and time of the start of the
measurement task that produced the
reported result values.
ma-report-result-end-time: An optional date and time indicating
when the measurement task that produced
the reported result values finished.
ma-report-result-conflicts: A possibly empty set of names of task
that might have impacted the
measurement being reported.
ma-report-result-values: A possibly empty set of result values.
3.7. Common Objects: 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) and when Schedule states what Tasks to run (with what configuration) 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
execute in parallel with such conflicts being reported in the execute in parallel with such conflicts being reported in the
skipping to change at page 20, line 15 skipping to change at page 24, line 27
association with the scheduled execution of the sending task - there association with the scheduled execution of the sending task - there
is no need for a corresponding input specification for the receiving is no need for a corresponding input specification for the receiving
task. While it is likely that an MA implementation will use a queue task. While it is likely that an MA implementation will use a queue
mechanism between the scheduled tasks, this Information Model does mechanism between the scheduled tasks, this Information Model does
not mandate or define a queue, or any potential associated parameters not mandate or define a queue, or any potential associated parameters
such as storage size and retention policies. such as storage size and retention policies.
When specifying the task to execute within the Schedule, it is When specifying the task to execute within the Schedule, it is
possible to add to the task configuration option parameters. This possible to add to the task configuration option parameters. This
allows the Task Configuration to determine the common characteristics allows the Task Configuration to determine the common characteristics
of a Task, while selected parameters (e.g. the test target URL) are of a Task, while selected parameters (e.g., the test target URL) are
defined within the schedule. A single Tasks Configuration can even defined within the schedule. A single Tasks Configuration can even
be used multiple times in the same schedule with different additional be used multiple times in the same schedule with different additional
parameters. This allows for efficiency in creating and transferring parameters. This allows for efficiency in creating and transferring
the Instruction. Note that the semantics of what happens if an the Instruction. Note that the semantics of what happens if an
option is defined multiple times (either in the Task Configuration, option is defined multiple times (either in the Task Configuration,
Schedule or in both) is not standardised and will depend upon the Schedule or in both) is not standardised and will depend upon the
Task. For example, some tasks may legitimately take multiple values Task. For example, some tasks may legitimately take multiple values
for a single parameter. for a single parameter.
Where Options are specified in both the Schedule and the Task Where Options are specified in both the Schedule and the Task
skipping to change at page 20, line 39 skipping to change at page 25, line 5
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 scheduled Reporting Task. This Reporting Task is to be sent to a scheduled Reporting Task. This Reporting Task is
executed by a separate Schedule that specifies that it should run executed by a separate Schedule that specifies that it should run
hourly at 5 minutes past the hour. When run this Reporting Task hourly at 5 minutes past the hour. When run this Reporting Task
takes the data generated by the UDP latency Task as well as any takes the data generated by the UDP latency Task as well as any
other data to be included in the hourly report and transfers it to other data to be included in the hourly report and transfers it to
the 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 3.7.1. Definition of ma-schedule-obj
object { object {
string ma-schedule-name; string ma-schedule-name;
ma-sched-task-obj ma-schedule-tasks<0..*>; ma-action-obj ma-schedule-actions<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 The ma-schedule-obj is the main scheduling object. It consists of
// Configuration and mappings of data outputs to destination tasks the following elements:
object { ma-schedule-name: A name uniquely identifying a scheduling
string ma-schedule-task-name; object.
[name-value-pair ma-schedule-task-options<0..*>];
[ma-sched-downstream-tasks-obj ma-schedule-destination-tasks<0..*>;]
} ma-sched-task-obj;
// Specification of destination scheduled tasks using reference ma-schedule-actions: A possibly empty list of actions to invoke
// to schedule and task configuration names. Mapping of when the schedule fires.
// integer denoted data outputs to destination scheduled task
object { ma-schedule-timing: A timing object indicating when the
[string ma-schedule-task-destination-schedule-name]; schedule fires.
[string ma-schedule-task-destination-task-configuration-name];
[int ma-schedule-task-output-selection<0..*>;] // default: all 3.7.2. Definition of ma-action-obj
} ma-sched-destination-tasks-obj;
object {
string ma-action-name;
string ma-action-task-name;
[ma-option-obj ma-action-task-options<0..*>];
[ma-action-dest-obj ma-action-destinations<0..*>;]
} ma-action-obj;
The ma-sched-action-obj models an a task together with its schedule
specific options and destination tasks. It consists of the following
elements:
ma-action-name: A name uniquely identifying an action of a
scheduling object.
ma-action-task-name: A name identifying the task to be invoked
by the action.
ma-action-task-options: An optional and possibly empty list of
options (name-value pairs) that are passed
to the task by appending them to the
options configured for the task object.
ma-action-destinations: An optional and possibly empty list of
destination actions that consume output
produced by this action.
3.7.3. Definition of ma-action-dest-obj
object {
string ma-action-dest-schedule-name;
string ma-action-dest-action-name;
[int ma-action-dest-action-outputs<0..*>;]
} ma-action-dest-obj;
The ma-action-dest-obj defines to which subsequent actions output
produced by an action should be sent to. It consists of the
following elements:
ma-action-dest-schedule-name: A name identifying a schedule object.
ma-action-dest-action-name: A name identifying an action within a
schedule object.
ma-action-dest-action-outputs: An optional and possibly empty list
of task outputs. If not present, the
element defaults to all outputs.
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 and 2. In this example, both
are sent to the same reporting task called "Hourly reporting Task" outputs are sent to the same reporting task called "Hourly
that is executed from the "Hourly Schedule" schedule. This is reporting Task" that is executed from the "Hourly Schedule"
done by creating a ma-sched-destination-tasks-obj with the output schedule. This is done by creating a ma-action-dest-obj with the
selection as [1,2] and the destination task configuration name as output selection as [1,2] and the destination action configuration
["Hourly Reporting Task"] and the destination schedule name as name as ["Hourly Reporting Task"] and the destination schedule
"Hourly Schedule". name as "Hourly Schedule".
Measurement Task Measurement Task
Output 1 -----+----> "Hourly Schedule":"Hourly Reporting Task" Output 1 -----+----> "Hourly Schedule":"Hourly Reporting Task"
Output 2 ----/ Output 2 ----/
3.7.2. Channels 3.8. Common Objects: 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 by the Schedule which executes the corresponding Control or specified by the Schedule which executes the corresponding Control or
skipping to change at page 22, line 31 skipping to change at page 27, line 32
Multiple interfaces are also supported. For example the Reporting Multiple interfaces are also supported. For example the Reporting
Task could be configured to send some results over GPRS. This is Task could be configured to send some results over GPRS. This is
especially useful when such results indicate the loss of connectivity especially useful when such results indicate the loss of connectivity
on a different network interface. on a 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. 3.8.1. Definition of ma-channel-obj
// Contains channel endpoint target URL and security credentials
// to establish secure channel. Optionally allows interface
// specification (by interface name string reference)
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.7.3. Task Configurations The ma-channel-obj consists of the following elements:
ma-channel-name: A unique name identifying the channel
object.
ma-channel-target: A URL identifying the target channel
endpoint.
ma-channel-credentials: The security credentials needed to
establish a secure channel.
ma-channel-interface-name: An optional name of the network interface
to be used. If not present, the system
will select a suitable interface.
3.9. Common Objects: 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 to enable the MA to uniquely identify the Tasks have a registry entry to enable the MA to uniquely identify the
Task it should execute and retrieve the schema for any parameters Task it should execute and retrieve the schema for any parameters
that may be passed to the Task. This registry entry is specified as that may be passed to the Task. This registry entry is specified as
skipping to change at page 24, line 19 skipping to change at page 29, line 31
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 3.9.1. Definition of ma-task-obj
// from Schedule. Contains URI to link to registry or local
// 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;
[ma-task-option ma-task-options<0..*>]; [ma-option-obj ma-task-options<0..*>];
[boolean ma-task-suppress-by-default;] // default: TRUE [boolean ma-task-suppress-by-default;]
[string ma-task-cycle-id;] [string ma-task-cycle-id;]
} ma-task-obj; } ma-task-obj;
While many of the Task Configuration Options are left to individual The ma-task-obj defines a task that can be invoked. A task can be
tasks to define, some common Options are used by multiple tasks and referenced via its name and it contains an URI to link to a registry
benefit from standardisation. These Options are Channel and Role. or a local specification of the task. Options allow the
configuration of task parameter (in the form of name-value pairs).
The ma-task-obj consists of the following elements:
Channel is used to specify the details of an endpoint for Control or ma-task-name: A name uniquely identifying a task
Reporting Task communications and is detailed elsewhere in this object.
document.
Role is used to specify which Role the task should be performing (as ma-task-registry-entry: A URI identifying the type of task.
defined in the registry) if multiple roles are available.
// General Task Option ma-task-options: A optional and possibly empty list of
options (name-value pairs) that are
passed to the task.
object { ma-task-suppress-by-default: A boolean flag indicating whether the
string ma-option-name; task will be suppressed by default.
object ma-option-value; The default value of the flag is true.
} ma-task-option
// Channel Option ma-task-cycle-id: An optional measurement cycle
identifier that can be used to identify
set of measurement results that have
been produced by tasks with comparable
options.
oobject { 3.9.2. Definition of ma-option-obj
string ma-option-name; // set to "channel"
string ma-option-value; // set to ma-channel-name reference
} ma-task-option
// Role Option object {
string ma-option-name;
[object ma-option-value;]
} ma-option-obj;
object { The ma-option-obj models a name-value pair and consists of the
string ma-option-name; // set to "role" following elements:
string ma-option-value; // set to registry role reference
} ma-task-option
3.7.4. Timing Information ma-option-name: The name of the option.
ma-option-value: The optional value of the option.
While many of the Task Configuration Options are left to individual
tasks to define, some common Options are used by multiple tasks and
benefit from standardisation. These Options are Channel and Role.
o Channel is used to specify the details of an endpoint for Control
or Reporting Task communications and is detailed elsewhere in this
document. The common option name for specifying the channel is
"channel".
o Role is used to specify which Role the task should be performing
(as defined in the registry) if multiple roles are available. The
common option name for specifying the role is "role".
3.10. Common Objects: 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
3. One Off: A single instance occurring at a specific time 3. One Off: A single instance occurring at a specific time
4. Immediate: Should occur as soon as possible 4. Immediate: Should occur as soon as possible
5. Startup: Should occur whenever the MA is started (e.g. at device 5. Startup: Should occur whenever the MA is started (e.g., at device
startup) startup)
Optionally each of the options may also specify a randomness that Optionally each of the options may also specify a randomness that
should be evaluated and applied separately to each indicated event. should be evaluated and applied separately to each indicated event.
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
skipping to change at page 26, line 20 skipping to change at page 31, line 36
Starup timing is only executed on device startup - not when a new Starup timing is only executed on device startup - not when a new
Instruction is transferred to the MA. If scheduled task execution is Instruction is transferred to the MA. If scheduled task execution is
desired both on the transfer of the Instruction and on device restart desired both on the transfer of the Instruction and on device restart
then both the Immediate and Startup timing needs to be used in then both the Immediate and Startup timing needs to be used in
conjunction. 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]. MUST conform to RFC 3339 [RFC3339].
// Main Timing object with name string to allow reference by Schedule 3.10.1. Definition of ma-timing-obj
// Must be specialised by one of the Timing options.
// 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;]
} ma-timing-obj; } ma-timing-obj;
3.7.4.1. Periodic Timing The ma-timing-obj is the main timing object. Timing objects are
identified by a name. The timing object itself contains a more
specific timing object. These objects are further described below.
Information model elements: The ma-timing-obj also includes an optional uniform random spread in
milliseconds that can be used to randomize the start times of
scheduled tasks. The ma-timing-obj consists of the following
elements:
// Timing specialisation to run a series of Tasks repeated at ma-timing-name: The name uniquely identifies a timing
// set intervals object. Schedules refer to timing objects
by this name.
object { ma-timing-periodic: The ma-timing-periodic is present for
[datetime ma-periodic start;] // default: immediate periodic timing objects.
[datetime ma-periodic-end;] // default: indefinite
int ma-periodic-interval; // milliseconds
} ma-periodic-obj;
3.7.4.2. Calendar Timing ma-timing-calendar: The ma-timing-calendar is present for
calendar timing objects.
ma-timing-one-off: The ma-timing-one-off is present for one-
off timing objects.
ma-timing-immediate: The ma-timing-immediate is present for
immediate timing objects.
ma-timing-startup: The ma-timing-startup is present for
startup timing objects.
ma-timing-random-spread: The optional ma-timing-random-spread adds a
random delay defined in milliseconds to the
timing object.
3.10.2. Definition of ma-periodic-obj
object {
[datetime ma-periodic-start;]
[datetime ma-periodic-end;]
int ma-periodic-interval;
} ma-periodic-obj;
The ma-periodic-obj timing object has an optional start and an
optional end time plus a periodic interval. Tasks scheduled using an
ma-periodic-obj are started periodically between the start and end
time. The ma-periodic-obj consists of the following elements:
ma-periodic-start: The optional date and time at which tasks
scheduled using this object are first
started. If not present it defaults to
immediate.
ma-periodic-end: The optional date and time at which tasks
scheduled using this object last started.
If not present it defaults to indefinite.
ma-periodic-interval: The interval defines the time in
milliseconds between two consecutive starts
of tasks.
3.10.3. Definition of ma-calendar-obj
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
times). If the optional timezone offset is not supplied then local times). If the optional timezone offset is not supplied then local
system time is assumed. This is essential in some use cases to system time is assumed. This is essential in some use cases to
ensure consistent peak-time measurements as well as supporting MA ensure consistent peak-time measurements as well as supporting MA
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",
"Wed", "Thu", "Fri", "Sat", "Sun".
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.
The calendar elements within the Calendar Timing do not have defaults The calendar elements within the Calendar Timing do not have defaults
in order to avoid accidental high-frequency execution of Tasks. If in order to avoid accidental high-frequency execution of Tasks. If
all possible values for an element are desired then the wildcard * is all possible values for an element are desired then the wildcard * is
used. used.
Information model elements: object {
[datetime ma-calendar-start;]
[datetime ma-calendar-end;]
[string ma-calendar-months<0..*>;]
[string ma-calendar-days-of-week<0..*>;]
[string ma-calendar-days-of-month<0..*>;]
[string ma-calendar-hours<0..*>;]
[string ma-calendar-minutes<0..*>;]
[string ma-calendar-seconds<0..*>;]
[int ma-calendar-timezone-offset;]
} ma-calendar-obj;
// Timing specialisation to run repeated Tasks at specific ma-calendar-start: The optional date and time at which
// times and/or days tasks scheduled using this object are
first started. If not present it
defaults to immediate.
object { ma-calendar-end: The optional date and time at which
[datetime ma-calendar-start;] // default: immediate tasks scheduled using this object last
[datetime ma-calendar-end;] // default: indefinite started. If not present it defaults to
[int ma-calendar-months<0..*>;] // values: 1-12,* indefinite.
[days ma-calendar-days-of-week<0..*>;]
// values: "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun",*
[int ma-calendar-days-of-month<0..*>;] // values 1-31,*
[int ma-calendar-hours<0..*>;] // values: 0-23,*
[int ma-calendar-minutes<0..*>;] // values: 0-59,*
[int ma-calendar-seconds<0..*>;] // values: 0-59,*
[int ma-calendar-timezone-offset;]
// default: system timezone offset
} ma-calendar-obj;
3.7.4.3. One-Off Timing ma-calendar-months: The optional set of months (1-12) on
which tasks scheduled using this object
are started. The wildcard * means all
months. If not present, it defaults to
no months.
Information model elements: ma-calendar-days-of-week: The optional set of days of a week
("Mon", "Tue", "Wed", "Thu", "Fri",
"Sat", "Sun") on which tasks scheduled
using this object are started. The
wildcard * means all days of teh week.
If not present, it defaults to no
months.
// Timing specialisation to run once at a specified time/date ma-calendar-days-of-month: The optional set of days of a months
(1-31) on which tasks scheduled using
this object are started. The wildcard
* means all days of a months. If not
present, it defaults to no days.
object { ma-calendar-hours: The optional set of hours (0-23) on
datetime ma-one-off-time; which tasks scheduled using this object
} ma-one-off-obj; are started. The wildcard * means all
hours of a day. If not present, it
defaults to no hours.
3.7.4.4. Immediate Timing ma-calendar-minutes: The optional set of minutes (0-59) on
which tasks scheduled using this object
are started. The wildcard * means all
minutes of an hour. If not present, it
defaults to no hours.
The immediate timing object has no further information elements. The ma-calendar-seconds: The optional set of seconds (0-59) on
measurement or report is simply to be done as soon as possible. which tasks scheduled using this object
are started. The wildcard * means all
seconds of an hour. If not present, it
defaults to no seconds.
// Timing specialisation to run immediately ma-calendar-timezone-offset: The optional timezone offest in hours.
If not present, it defaults to the
system's local timezone..
object { If a day of the month is specified that does not exist in the month
// empty (e.g., 29th of Feburary) then those values are ignored.
} ma-immediate-obj;
3.7.4.5. Startup Timing 3.10.4. Definition of ma-one-off-obj
The immediate timing object has no further information elements. The object {
measurement or report is simply done at MA initiation. datetime ma-one-off-time;
} ma-one-off-obj;
// Timing specialisation to run at MA startup The ma-one-off-obj timing object specifies a fixed point in time.
Tasks scheduled using an ma-one-off-obj are started once at the
specified date and time. The ma-one-off-obj consists of the
following elements:
object { ma-one-off-time: The date and time at which tasks scheduled
using this object are started.
3.10.5. Definition of ma-immediate-obj
object {
// empty // empty
} ma-startup-obj; } ma-immediate-obj;
The ma-immediate-obj timing object has no further information
elements. Tasks scheduled using an ma-immediate-obj are started as
soon as possible.
3.10.6. Definition of ma-startup-obj
object {
// empty
} ma-startup-obj;
The ma-startup-obj timing object has no further information elements.
Tasks scheduled using an ma-startup-obj are started at MA initiation
time.
4. IANA Considerations 4. IANA Considerations
This document makes no request of IANA. This document makes no request of IANA.
Note to RFC Editor: this section may be removed on publication as an Note to RFC Editor: this section may be removed on publication as an
RFC. RFC.
5. Security Considerations 5. Security Considerations
skipping to change at page 29, line 36 skipping to change at page 36, line 46
Schoenwaelder work in part on the Leone research project, which Schoenwaelder work in part on the Leone research project, which
receives funding from the European Union Seventh Framework Programme receives funding from the European Union Seventh Framework Programme
[FP7/2007-2013] under grant agreement number 317647. [FP7/2007-2013] under grant agreement number 317647.
7. References 7. References
7.1. Normative References 7.1. Normative References
[I-D.ietf-lmap-framework] [I-D.ietf-lmap-framework]
Eardley, P., Morton, A., Bagnulo, M., Burbridge, T., Eardley, P., Morton, A., Bagnulo, M., Burbridge, T.,
Aitken, P., and A. Akhter, "A framework for large-scale Aitken, P., and A. Akhter, "A framework for Large-Scale
measurement platforms (LMAP)", draft-ietf-lmap- Measurement of Broadband Performance (LMAP)", draft-ietf-
framework-10 (work in progress), January 2015. lmap-framework-12 (work in progress), March 2015.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the
Internet: Timestamps", RFC 3339, July 2002. Internet: Timestamps", RFC 3339, July 2002.
7.2. Informative References 7.2. Informative References
[I-D.ietf-ippm-metric-registry] [I-D.ietf-ippm-metric-registry]
Bagnulo, M., Claise, B., Eardley, P., Morton, A., and A. Bagnulo, M., Claise, B., Eardley, P., Morton, A., and A.
Akhter, "Registry for Performance Metrics", draft-ietf- Akhter, "Registry for Performance Metrics", draft-ietf-
ippm-metric-registry-01 (work in progress), September ippm-metric-registry-02 (work in progress), February 2015.
2014.
[I-D.schoenw-lmap-yang] [I-D.ietf-lmap-yang]
Schoenwaelder, J. and V. Bajpai, "A YANG Data Model for Schoenwaelder, J. and V. Bajpai, "A YANG Data Model for
LMAP Measurement Agents", draft-schoenw-lmap-yang-02 (work LMAP Measurement Agents", draft-ietf-lmap-yang-00 (work
in progress), January 2015. in progress), April 2015.
[RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between [RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between
Information Models and Data Models", RFC 3444, January Information Models and Data Models", RFC 3444, January
2003. 2003.
Appendix A. JSON Data Model Example
In order to give an example of data in the Information Model we need
to select a data model language. In the following example we have
expressed the Data Model using JSON as this will be of direct
interest to some Control and Report Protocols. A YANG data model
implementation of the Information Model is provided in a separate
draft [I-D.schoenw-lmap-yang].
The example is broken down into a number of different steps that
might adhere to the steps within a Control and Report Protocol:
1. Pre-configuration.
2. Configuration
3. Capabilities
4. Instruction
5. Report
6. Suppression
While the pre-configuration is not delivered as part of the Control
Protocol, the same JSON data model is used for consistency and to aid
the reader.
//Pre-configuration
{
"ma-config": {
"ma-agent-id": "550e8400-e29b-41d4-a716-446655440000",
"ma-control-tasks": [
{
"ma-task-name": "Controller configuration",
"ma-task-registry-entry":
"urn:ietf:lmap:control:http_controller_configuration",
"ma-task-options": [{"name": "channel",
"value": "Controller channel"}]
}
],
"ma-control-channels": [
{
"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-credentials": { }
}
}
Given the pre-configuration information the MA is able to contact the
Controller and receive an updated/expanded Configuration. In this
example additional Control Protocol tasks to post Status and
Capabilities to the Controller and fetch the Instruction are added as
well as moving the schedule timing for contacting the Controller to
hourly.
// Configuration
{
"ma-config": {
"ma-agent-id": "550e8400-e29b-41d4-a716-446655440000",
"ma-control-tasks": [
{
"ma-task-name": "Controller configuration",
"ma-task-registry-entry":
"urn:ietf:lmap:control:http_controller_configuration",
"ma-task-options": [{"name": "channel",
"value": "Controller channel"}]
},
{
"ma-task-name": "Controller status and capabilities",
"ma-task-registry-entry":
"urn:ietf:lmap:control:http_control_status_and_capabilities",
"ma-task-options": [{"name": "channel",
"value": "Controller channel"}]
},
{
"ma-task-name": "Controller instruction",
"ma-task-registry-entry":
"urn:ietf:lmap:control:http_controller_instruction",
"ma-task-options": [{"name": "channel",
"value": "Controller channel"}]
}
],
"ma-control-channels": [
{
"ma-channel-name": "Controller channel",
"ma-channel-target": "http://www.example.com/lmap/controller",
"ma-channel-credientials": { }
}
],
"ma-control-schedules": [
{
"ma-schedule-name": "Controller schedule",
"ma-schedule-tasks": [
{
"ma-schedule-task-name": "Controller configuration",
},
{
"ma-schedule-task-name":
"Controller status and capabilities",
},
{
"ma-schedule-task-name": "Controller instruction",
}
],
"ma-schedule-timing": {
"ma-timing-name": "hourly randomly",
"ma-timing-calendar": {
"ma-calendar-minutes": ["00"],
"ma-calendar-seconds": ["00"]
},
"ma-timing-random-spread": "3600000"
}
}
],
"ma-credentials": { }
}
}
The above configuration now contacts the Controller randomnly within
each hour. The following is an example of the Status and
Capabilities information that is transferred from the MA to the
Controller.
// Status and Capabilities
{
"ma-status-and-capabilities": {
"ma-agent-id": "550e8400-e29b-41d4-a716-446655440000",
"ma-device-id": "urn:dev:mac:0024befffe804ff1",
"ma-hardware": "mfr-home-gateway-v10",
"ma-firmware": "25637748-rev2a",
"ma-version": "ispa-v1.01",
"ma-interfaces": [
{
"ma-interface-name": "broadband",
"ma-interface-type": "PPPoE"
}
],
"ma-last-task": "",
"ma-last-report": "",
"ma-last-instruction": "",
"ma-last-configuration": "2014-06-08T22:47:31+00:00",
"ma-supported-tasks": [
{
"ma-task-name": "Controller configuration",
"ma-task-registry":
"urn:ietf:lmap:control:http_controller_configuration"
},,
{
"ma-task-name": "Controller status and capabilities",
"ma-task-registry":
"urn:ietf:lmap:control:http_control_status_and_capabilities"
},
{
"ma-task-name": "Controller instruction",
"ma-task-registry":
"urn:ietf:lmap:control:http_controller_instruction"
},
{
"ma-task-name": "Report",
"ma-task-registry": "urn:ietf:lmap:report:http_report"
},
{
"ma-task-name": "UDP Latency",
"ma-task-registry":
"urn:ietf:ippm:measurement:UDPLatency-Poisson-XthPercMean"
}
]
}
}
After fetching the status and capabilties the Controller issues and
Instruction to the MA to perform a single UDP latency measurement
task 4 times a day and to report the results immediately.
// Instruction
{
"ma-instruction": {
"ma-instruction-tasks": [
{
"ma-task-name": "UDP Latency",
"ma-task-registry-entry":
"urn:ietf:ippm:measurement:UDPLatency-Poisson-XthPercMean",
"ma-task-options": [
{"name": "X", "value": "99"},
{"name":"rate", "value": "5"},
{"name":"duration", "value": "30.000"},
{"name":"interface", "value": "broadband"},
{"name":"destination-ip",
"value": {"version":"ipv4", "ip-address":"192.168.2.54"}},
{"name":"destination-port", "value": "50000"},
{"name":"source-port", "value": "50000"}
],
"ma-task-suppress-by-default": "TRUE"
},
{
"ma-task-name": "Report",
"ma-task-registry-entry": "urn:ietf:lmap:report:http_report",
"ma-task-options": [
{"name": "report-with-no-data", "value": "FALSE"},
{"name": "channel", "value": "Collector A"]}
],
"ma-task-suppress-by-default": "FALSE"
}
],
"ma-report-channels": [
{
"ma-channel-name": "Collector A",
"ma-channel-target": "http://www.example2.com/lmap/collector",
"ma-channel-credientials": { }
}
],
"ma-instruction-schedules": [
{
"ma-schedule-name": "4 times daily test UDP latency and report",
"ma-schedule-tasks": [
{
"ma-schedule-task-name": "UDP Latency",
"ma-schedule-destination-tasks": [
{
"ma-schedule-task-output-selection": [1],
"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-timing": {
"ma-timing-name": "once every 6 hours",
"ma-timing-calendar": {
"ma-calendar-hours": ["00", "06", "12", "18"],
"ma-calendar-minutes": ["00"],
"ma-calendar-seconds": ["00"]
},
"ma-timing-random-spread": "21600000"
}
}
]
}
}
The report task in the Instruction is executed immediately after the
UDP test and transfers the following data to the Collector.
// Report
{
"ma-report": {
"ma-report-date": "2014-06-09T02:30:45+00:00",
"ma-report-agent-id": "550e8400-e29b-41d4-a716-446655440000",
"ma-report-tasks": [
{
"ma-report-task-name": "UDP Latency",
"ma-report-task-registry-entry":
"urn:ietf:ippm:measurement:UDPLatency-Poisson-XthPercMean",
"ma-report-scheduled-task-options": [
{"name": "X", "value": "99"},
{"name":"rate", "value": "5"},
{"name":"duration", "value": "30.000"},
{"name":"interface", "value": "broadband"},
{"name":"destination-ip",
"value": {"version":"ipv4", "ip-address":"192.168.2.54"}},
{"name":"destination-port", "value": "50000"},
{"name":"source-port", "value": "50000"}
],
"ma-report-task-column-labels":
["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
test and issues a Suppression Instruction. Since the task is marked
as suppressible by default, simply turning on suppression will stop
the task being executed in future.
// Suppression
{
"ma-instruction": {
"ma-suppression": {
"ma-suppression-enabled": "TRUE"
}
}
}
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. 113 change blocks. 
654 lines changed or deleted 704 lines changed or added

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