Tech-invite3GPPspecsGlossariesIETFRFCsGroupsSIPABNFsWorld Map

RFC 8193

Proposed STD
Pages: 53
Top     in Index     Prev     Next
in Group Index     Prev in Group     Next in Group     Group: LMAP

Information Model for Large-Scale Measurement Platforms (LMAPs)

Part 1 of 3, p. 1 to 18
None       Next Section

 


Top       ToC       Page 1 
Internet Engineering Task Force (IETF)                      T. Burbridge
Request for Comments: 8193                                    P. Eardley
Category: Standards Track                                             BT
ISSN: 2070-1721                                               M. Bagnulo
                                        Universidad Carlos III de Madrid
                                                        J. Schoenwaelder
                                                Jacobs University Bremen
                                                             August 2017


    Information Model for Large-Scale Measurement Platforms (LMAPs)

Abstract

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

Status of This Memo

   This is an Internet Standards Track document.

   This document is a product of the Internet Engineering Task Force
   (IETF).  It represents the consensus of the IETF community.  It has
   received public review and has been approved for publication by the
   Internet Engineering Steering Group (IESG).  Further information on
   Internet Standards is available in Section 2 of RFC 7841.

   Information about the current status of this document, any errata,
   and how to provide feedback on it may be obtained at
   http://www.rfc-editor.org/info/rfc8193.

Top      ToC       Page 2 
Copyright Notice

   Copyright (c) 2017 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
   2.  Requirements Language . . . . . . . . . . . . . . . . . . . .   4
   3.  Notation  . . . . . . . . . . . . . . . . . . . . . . . . . .   5
   4.  LMAP Information Model  . . . . . . . . . . . . . . . . . . .   6
     4.1.  Preconfiguration Information  . . . . . . . . . . . . . .  10
       4.1.1.  Definition of ma-preconfig-obj  . . . . . . . . . . .  11
     4.2.  Configuration Information . . . . . . . . . . . . . . . .  12
       4.2.1.  Definition of ma-config-obj . . . . . . . . . . . . .  13
     4.3.  Instruction Information . . . . . . . . . . . . . . . . .  14
       4.3.1.  Definition of ma-instruction-obj  . . . . . . . . . .  17
       4.3.2.  Definition of ma-suppression-obj  . . . . . . . . . .  17
     4.4.  Logging Information . . . . . . . . . . . . . . . . . . .  19
       4.4.1.  Definition of ma-log-obj  . . . . . . . . . . . . . .  20
     4.5.  Capability and Status Information . . . . . . . . . . . .  21
       4.5.1.  Definition of ma-capability-obj . . . . . . . . . . .  21
       4.5.2.  Definition of ma-capability-task-obj  . . . . . . . .  21
       4.5.3.  Definition of ma-status-obj . . . . . . . . . . . . .  22
       4.5.4.  Definition of ma-status-schedule-obj  . . . . . . . .  23
       4.5.5.  Definition of ma-status-action-obj  . . . . . . . . .  24
       4.5.6.  Definition of ma-status-suppression-obj . . . . . . .  26
       4.5.7.  Definition of ma-status-interface-obj . . . . . . . .  27
     4.6.  Reporting Information . . . . . . . . . . . . . . . . . .  28
       4.6.1.  Definition of ma-report-obj . . . . . . . . . . . . .  29
       4.6.2.  Definition of ma-report-result-obj  . . . . . . . . .  30
       4.6.3.  Definition of ma-report-conflict-obj  . . . . . . . .  32
       4.6.4.  Definition of ma-report-table-obj . . . . . . . . . .  32
       4.6.5.  Definition of ma-report-row-obj . . . . . . . . . . .  33
     4.7.  Common Objects: Schedules . . . . . . . . . . . . . . . .  33
       4.7.1.  Definition of ma-schedule-obj . . . . . . . . . . . .  35
       4.7.2.  Definition of ma-action-obj . . . . . . . . . . . . .  36

Top      ToC       Page 3 
     4.8.  Common Objects: Channels  . . . . . . . . . . . . . . . .  37
       4.8.1.  Definition of ma-channel-obj  . . . . . . . . . . . .  38
     4.9.  Common Objects: Task Configurations . . . . . . . . . . .  38
       4.9.1.  Definition of ma-task-obj . . . . . . . . . . . . . .  40
       4.9.2.  Definition of ma-option-obj . . . . . . . . . . . . .  40
     4.10. Common Objects: Registry Information  . . . . . . . . . .  41
       4.10.1.  Definition of ma-registry-obj  . . . . . . . . . . .  41
     4.11. Common Objects: Event Information . . . . . . . . . . . .  41
       4.11.1.  Definition of ma-event-obj . . . . . . . . . . . . .  42
       4.11.2.  Definition of ma-periodic-obj  . . . . . . . . . . .  44
       4.11.3.  Definition of ma-calendar-obj  . . . . . . . . . . .  44
       4.11.4.  Definition of ma-one-off-obj . . . . . . . . . . . .  46
       4.11.5.  Definition of ma-immediate-obj . . . . . . . . . . .  47
       4.11.6.  Definition of ma-startup-obj . . . . . . . . . . . .  47
       4.11.7.  Definition of ma-controller-lost-obj . . . . . . . .  47
       4.11.8.  Definition of ma-controller-connected-obj  . . . . .  47
   5.  Example Execution . . . . . . . . . . . . . . . . . . . . . .  48
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  49
   7.  Security Considerations . . . . . . . . . . . . . . . . . . .  50
   8.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  50
     8.1.  Normative References  . . . . . . . . . . . . . . . . . .  50
     8.2.  Informative References  . . . . . . . . . . . . . . . . .  51
   Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .  52
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  53

1.  Introduction

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

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

Top      ToC       Page 4 
   A large-scale measurement platform involves basically three types of
   protocols, namely, a Control Protocol (or Protocols) between a
   Controller and the MAs, a Report Protocol (or Protocols) between the
   MAs and the Collector(s), and several measurement protocols between
   the MAs and Measurement Peers (MPs), used to actually perform the
   measurements.  In addition, some information is required to be
   configured on the MA prior to any communication with a Controller.

   This document defines the Information Model for both the Control and
   Report Protocols along with Preconfiguration Information that is
   required on the MA before communicating with the Controller, broadly
   named as the LMAP Information Model.  The measurement protocols are
   out of the scope of this document.

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

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

   1.  To guide the standardization of one or more Control and Report
       protocols and data models

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

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

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

2.  Requirements Language

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in BCP
   14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

Top      ToC       Page 5 
3.  Notation

   This document uses a notation similar to a programming language to
   define the properties of the objects of the Information Model.  An
   optional property is enclosed by square brackets, [ ], and a list
   property is indicated by two numbers in angle brackets, <m..n>, where
   m indicates the minimal number of values, and n is the maximum.  The
   symbol * for n means no upper bound.

   The object definitions use several base types that are defined as
   follows:

   int         A type representing signed or unsigned integer numbers.
               This Information Model does not define a precision nor
               does it make a distinction between signed and unsigned
               number ranges.  This type is also used to represent
               enumerations.

   boolean     A type representing a boolean value.

   string      A type representing a human-readable string consisting of
               a (possibly restricted) subset of Unicode and ISO/IEC
               10646 [ISO.10646] characters.

   datetime    A type representing a date and time using the Gregorian
               calendar.  The datetime format MUST conform to RFC 3339
               [RFC3339].

   uuid        A type representing a Universally Unique IDentifier
               (UUID) as defined in RFC 4122 [RFC4122].  The UUID values
               are expected to be unique within an installation of a
               large-scale measurement system.

   uri         A type representing a Uniform Resource Identifier as
               defined in STD 66 [RFC3986].

   ip-address  A type representing an IP address.  This type supports
               both IPv4 and IPv6 addresses.

   counter     A non-negative integer that monotonically increases.
               Counters may have discontinuities, and they are not
               expected to persist across restarts.

   credentials An opaque type representing credentials needed by a
               cryptographic mechanism to secure communication.  Data
               models must expand this opaque type as needed and
               required by the security protocols utilized.

Top      ToC       Page 6 
   data        An opaque type representing data obtained from
               measurements.

   Names of objects are generally assumed to be unique within an
   implementation.

4.  LMAP Information Model

   The information described herein relates to the information stored,
   received, or transmitted by a Measurement Agent as described within
   the LMAP framework [RFC7594].  As such, some subsets of this
   Information Model are applicable to the measurement Controller and
   Collector and to any device management system that preconfigures the
   Measurement Agent.  The information described in these models will be
   transmitted by protocols using interfaces between the Measurement
   Agent and such systems according to a data model.

   The Information Model is divided into six aspects.  Firstly, the
   grouping of information facilitates reader understanding.  Secondly,
   the particular groupings chosen are expected to map to different
   protocols or different transmissions within those protocols.

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

   2.  Configuration Information.  Update of the Preconfiguration
       Information during the registration of the MA or subsequent
       communication with the Controller, along with the configuration
       of further parameters about the MA (rather than the Measurement
       Tasks it should perform) that were not mandatory for the initial
       communication between the MA and a Controller.

   3.  Instruction Information.  Information that is received by the MA
       from the Controller pertaining to the Measurement Tasks that
       should be executed.  This includes the Task execution Schedules
       (other than the Controller communication Schedule supplied as
       Configuration or Preconfiguration Information) and related
       information such as the Task Configuration, communication
       Channels to Collectors, and Event information.  It also includes
       Task Suppression information that is used to override normal Task
       execution.

Top      ToC       Page 7 
   4.  Logging Information.  Information transmitted from the MA to the
       Controller detailing the results of any configuration operations
       along with error and Status Information from the operation of the
       MA.

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

   6.  Reporting Information.  Information transmitted from the MA to
       one or more Collectors, including measurement results and the
       context in which they were conducted.

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

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

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

Top      ToC       Page 8 
   The information modeled by the six aspects of the Information Model
   is supported by a number of common information objects.  These
   objects are also described later in this document and are comprised
   of:

   a.  Schedules.  A set of Schedules tells the MA to execute Actions.
       An Action of a Schedule leads to the execution of a Task.
       Without a Schedule, no Task (including measurements or reporting
       or communicating with the Controller) is ever executed.
       Schedules are used within the Instruction to specify what Tasks
       should be performed, when, and how to direct their results.  A
       Schedule is also used within the Preconfiguration and
       Configuration Information in order to execute the Task or Tasks
       required to communicate with the Controller.  A specific Schedule
       can only be active once.  Attempts to start a Schedule while the
       same Schedule is still running will fail.

   b.  Channels.  A set of Channel objects are used to communicate with
       a number of endpoints (i.e., the Controller and Collectors).
       Each Channel object contains the information required for the
       communication with a single endpoint such as the target location
       and security details.

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

   d.  Events.  A set of Event objects that can be referenced from the
       Schedules.  Each Schedule always references exactly one Event
       object that determines when the Schedule is executed.  An Event
       object specifies either a singleton or a series of Events that
       indicate when Tasks should be executed.  A commonly used kind of
       Event object is the Timing object.  For Event objects specifying
       a series of Events, it is generally a good idea to configure an
       end time and to refresh the end time as needed to ensure that MAs
       that lose connectivity to their Controller do not continue
       executing Schedules forever.

   Figure 1 illustrates the structure in which these common information
   objects are referenced.  The references are achieved by each object
   (Task Configuration, Event) being given a short textual name that is
   used by other objects.  The objects shown in parenthesis 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 selected Task
   Configurations but are similarly referenced using a short text name.

Top      ToC       Page 9 
        Schedule
           |-- triggered by --> Event
           |
           |-- executes --> Action 1
           |                  |-- using --> Task Configuration
           |                  |
           |                  `-- feeding to --> Destination Schedule
           :
           :
           `-- executes --> Action N
                              |-- using --> Task Configuration
                              |
                              `-- feeding to --> Destination Schedule

      Figure 1: Relationship between Schedules, Events, Actions, Task
                 Configurations, and Destination Schedules

   The primary function of an MA is to execute Schedules.  A Schedule,
   which is triggered by an Event, executes a number of Actions.  An
   Action refers to a configured Task, and it may feed results to a
   Destination Schedule.  Both Actions and configured Tasks can provide
   parameters, represented as Action Options and Task Options.

   Tasks can implement a variety of different functions.  While in terms
   of the Information Model, all Tasks have the same structure, it can
   help conceptually to think of different Task categories:

   1.  Measurement Tasks measure some aspect of network performance or
       traffic.  They may also capture contextual information from the
       MA device or network interfaces such as the device type or
       interface speed.

   2.  Data Transfer Tasks support the communication with a Controller
       and Collectors:

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

       B.  One or more Control Tasks implement the Control Protocol and
           communicate with the Controller

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

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

Top      ToC       Page 10 
   Figure 1 indicates that Actions can produce data that is fed into
   Destination Schedules.  This can by used by Actions implementing
   Measurement Tasks to feed measurement results to a Schedule that
   triggers Actions implementing Reporting Tasks.  Data fed to a
   Destination Schedule is consumed by the first Action of the
   Destination Schedule if the Destination Schedule is using the
   sequential or pipelined execution mode, and it is consumed by all
   Actions of the Destination Schedule if the Destination Schedule is
   using parallel execution mode.

4.1.  Preconfiguration Information

   This information is the minimal information that needs to be
   preconfigured to the MA in order for it to successfully communicate
   with a Controller during the registration process.  Some of the
   Preconfiguration Information elements are repeated in the
   Configuration Information in order to allow an LMAP Controller to
   update these items.  The Preconfiguration Information also contains
   some elements that are not under the control of the LMAP framework
   (such as the device identifier and device security credentials).

   This Preconfiguration Information needs to include a URL of the
   initial Controller from where Configuration Information can be
   communicated along with the security information required for the
   communication, including the certificate of the Controller (or the
   certificate of the Certification Authority that was used to issue the
   certificate for the Controller).  All this is expressed as a Channel.
   While multiple Channels may be provided in the Preconfiguration
   Information, they must all be associated with a single Controller
   (e.g., over different interfaces or network protocols).

   Where the MA pulls information from the Controller, the
   Preconfiguration Information also needs to contain the timing of the
   communication with the Controller as well as the nature of the
   communication itself (such as the protocol and data to be
   transferred).  The timing is represented as an Event that invokes a
   Schedule that executes the Task(s) responsible for communication with
   the Controller.  It is this Task (or Tasks) that implements the
   Control Protocol between the MA and the Controller and utilizes the
   Channel information.  The Task(s) may take additional parameters, as
   defined by a Task Configuration.

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

Top      ToC       Page 11 
   It can be seen that these Channels, Schedules, and Task
   Configurations for the initial communication between the MA and its
   Controller are no different in terms of the Information Model to any
   other Channel, Schedule, or Task Configuration that might execute a
   Measurement Task or report the measurement results (as described
   later).

   The MA may be preconfigured with an MA-ID or may use a Device ID in
   the first Controller contact before it is assigned an MA-ID.  The
   Device ID may be a Media Access Control (MAC) address or some other
   device identifier expressed as a URI.  If the MA-ID is not provided
   at this stage, then it must be provided by the Controller during
   Configuration.

4.1.1.  Definition of ma-preconfig-obj

     object {
         [uuid                ma-preconfig-agent-id;]
          ma-task-obj         ma-preconfig-control-tasks<1..*>;
          ma-channel-obj      ma-preconfig-control-channels<1..*>;
          ma-schedule-obj     ma-preconfig-control-schedules<1..*>;
         [uri                 ma-preconfig-device-id;]
          credentials         ma-preconfig-credentials;
     } ma-preconfig-obj;

   The ma-preconfig-obj describes information that needs to be available
   to the MA in order to bootstrap communication with a Controller.  The
   ma-preconfig-obj consists of the following elements:

   ma-preconfig-agent-id:          An optional UUID uniquely identifying
                                   the Measurement Agent.

   ma-preconfig-control-tasks:     An unordered set of Task objects.

   ma-preconfig-control-channels:  An unordered set of Channel objects.

   ma-preconfig-control-schedules: An unordered set of scheduling
                                   objects.

   ma-preconfig-device-id:         An optional identifier for the
                                   device.

   ma-preconfig-credentials:       The security credentials used by the
                                   Measurement Agent.

Top      ToC       Page 12 
4.2.  Configuration Information

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

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

   In addition, the MA will be given further items of information that
   relate specifically to the MA rather than the measurements it is to
   conduct or how to report results.  The assignment of an identifier to
   the Measurement Agent is mandatory.  If the Measurement Agent
   Identifier was not optionally provided during the preconfiguration,
   then one must be provided by the Controller during Configuration.
   Optionally, a Group-ID may also be given that identifies a group of
   interest to which that MA belongs.  For example, the group could
   represent an ISP, broadband product, technology, market
   classification, geographic region, or a combination of multiple such
   characteristics.  Additional flags control whether the MA-ID or the
   Group-ID are included in Reports.  The reporting of a Group-ID
   without the MA-ID may allow the MA to remain anonymous, which may be
   particularly useful to prevent tracking of mobile MA devices.

   Optionally, an MA can also be configured to stop executing any
   Instruction Schedule if the Controller is unreachable.  This can be
   used as a fail-safe to stop Measurement and other Tasks from being
   conducted when there is doubt that the Instruction Information is
   still valid.  This is simply represented as a time window in seconds
   since the last communication with the Controller, after which an
   Event is generated that can trigger the suspension of Instruction
   Schedules.  The appropriate value of the time window will depend on

Top      ToC       Page 13 
   the specified communication Schedule with the Controller and the
   duration for which the system is willing to tolerate continued
   operation with potentially stale Instruction Information.

   While Preconfiguration Information is persistent upon a device reset
   or power cycle, the persistency of the Configuration Information may
   be device dependent.  Some devices may revert back to their
   preconfiguration state upon reboot or factory reset, while other
   devices may store all Configuration and Instruction Information in
   persistent storage.  A Controller can check whether an MA has the
   latest Configuration and Instruction Information by examining the
   Capability and Status Information for the MA.

4.2.1.  Definition of ma-config-obj

     object {
         uuid                ma-config-agent-id;
         ma-task-obj         ma-config-control-tasks<1..*>;
         ma-channel-obj      ma-config-control-channels<1..*>;
         ma-schedule-obj     ma-config-control-schedules<1..*>;
         credentials         ma-config-credentials;
        [string              ma-config-group-id;]
        [string              ma-config-measurement-point;]
        [boolean             ma-config-report-agent-id;]
        [boolean             ma-config-report-group-id;]
        [boolean             ma-config-report-measurement-point;]
        [int                 ma-config-controller-timeout;]
     } ma-config-obj;

   The ma-config-obj consists of the following elements:

   ma-config-agent-id:                 A UUID uniquely identifying the
                                       Measurement Agent.

   ma-config-control-tasks:            An unordered set of Task objects.

   ma-config-control-channels:         An unordered set of Channel
                                       objects.

   ma-config-control-schedules:        An unordered set of scheduling
                                       objects.

   ma-config-credentials:              The security credentials used by
                                       the Measurement Agent.

   ma-config-group-id:                 An optional identifier of the
                                       group of Measurement Agents this
                                       Measurement Agent belongs to.

Top      ToC       Page 14 
   ma-config-measurement-point:        An optional identifier for the
                                       measurement point indicating
                                       where the Measurement Agent is
                                       located on a path (see [RFC7398]
                                       for further details).

   ma-config-report-agent-id:          An optional flag indicating
                                       whether the Agent Identifier
                                       (ma-config-agent-id) is included
                                       in reports.  The default value is
                                       true.

   ma-config-report-group-id:          An optional flag indicating
                                       whether the Group-ID
                                       (ma-config-group-id) is included
                                       in reports.  The default value is
                                       false.

   ma-config-report-measurement-point: An optional flag indicating
                                       whether the measurement point
                                       (ma-config-measurement-point)
                                       should be included in reports.
                                       The default value is false.

   ma-config-controller-timeout:       A timer is started after each
                                       successful contact with a
                                       Controller.  When the timer
                                       reaches the controller-timeout
                                       (measured in seconds), an Event
                                       is raised indicating that
                                       connectivity to the Controller
                                       has been lost (see
                                       ma-controller-lost-obj).

4.3.  Instruction Information

   The Instruction Information Model has four sub-elements:

   1.  Instruction Task Configurations

   2.  Report Channels

   3.  Instruction Schedules

   4.  Suppression

Top      ToC       Page 15 
   The Instruction supports the execution of all Tasks on the MA except
   those that deal with communication with the Controller (specified in
   Configuration or Preconfiguration Information).  The Tasks are
   configured in Instruction Task Configurations and included by
   reference in the Actions of Instruction Schedules that specify when
   to execute them.  The results can be communicated to other Schedules,
   or a Task may implement a Reporting Protocol and communicate results
   over Report Channels.  Suppression is used to temporarily stop the
   execution of new Tasks as specified by the Instruction Schedules (and
   optionally to stop ongoing Tasks).

   A Task Configuration is used to configure the mandatory and optional
   parameters of a Task.  It also serves to instruct the MA about the
   Task including the ability to resolve the Task to an executable and
   to specify the schema for the Task parameters.

   A Report Channel defines how to communicate with a single remote
   system specified by a URL.  A Report Channel is used to send results
   to a single Collector but is no different in terms of the Information
   Model to the Control Channel used to transfer information between the
   MA and the Controller.  Several Report Channels can be defined to
   enable results to be split or duplicated across different
   destinations.  A single Channel can be used by multiple (reporting)
   Task Configurations to transfer data to the same Collector.  A single
   Reporting Task Configuration can also be included in multiple
   Schedules.  For example, a single Collector may receive data at three
   different cycle rates, with one Schedule reporting hourly, another
   reporting daily, and a third specifying that results should be sent
   immediately for on-demand Measurement Tasks.  Alternatively, multiple
   Report Channels can be used to send Measurement Task results to
   different Collectors.  The details of the Channel element is
   described later as it is common to several objects.

   Instruction Schedules specify which Actions to execute according to a
   given triggering Event.  An Action extends a configured Task with
   additional specific parameters.  An Event can trigger the execution
   of a single Action, or it can trigger a repeated series of Actions.
   The Schedule also specifies how to link output data from Tasks to
   other Schedules.

   Measurement Suppression information is used to override the
   Instruction Schedule and temporarily stop measurements or other Tasks
   from running on the MA for a defined or indefinite period.  While
   conceptually measurements can be stopped by simply removing them from
   the Measurement Schedule, splitting out separate information on
   Measurement Suppression allows this information to be updated on the
   MA on a different timing cycle or protocol implementation to the
   Measurement Schedule.  It is also considered that it will be easier

Top      ToC       Page 16 
   for a human operator to implement a temporary explicit Suppression
   rather than having to move to a reduced Schedule and then roll back
   at a later time.

   It should be noted that Control Schedules and Tasks cannot be
   suppressed as evidenced by the lack of Suppression information in the
   Configuration.  The Control Schedule must only reference Tasks listed
   as Control Tasks (i.e., within the Configuration Information).

   A single Suppression object is able to enable/disable a set of
   Instruction Tasks that are tagged for Suppression.  This enables
   fine-grained control on which Tasks are suppressed.  Suppression of
   both matching Actions and Measurement Schedules is supported.
   Support for disabling specific Actions allows malfunctioning or
   misconfigured Tasks or Actions that have an impact on a particular
   part of the network infrastructure (e.g., a particular Measurement
   Peer) to be targeted.  Support for disabling specific Schedules
   allows for particularly heavy cycles or sets of less essential
   Measurement Tasks to be suppressed quickly and effectively.  Note
   that Suppression has no effect on either Controller Tasks or
   Controller Schedules.

   Suppression stops new Tasks from executing.  In addition, the
   Suppression information also supports an additional boolean that is
   used to select whether ongoing Tasks are also to be terminated.

   Unsuppression is achieved through either overwriting the Measurement
   Suppression information (e.g., changing 'enabled' to False) or
   through the use of an end time such that the Measurement Suppression
   will no longer be in effect beyond this time.

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

Top      ToC       Page 17 
4.3.1.  Definition of ma-instruction-obj

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

   An ma-instruction-obj consists of the following elements:

   ma-instruction-tasks:         A possibly empty unordered set of Task
                                 objects.

   ma-instruction-channels:      A possibly empty unordered set of
                                 Channel objects.

   ma-instruction-schedules:     A possibly empty unordered set of
                                 Schedule objects.

   ma-instruction-suppressions:  An optional possibly empty unordered
                                 set of Suppression objects.

4.3.2.  Definition of ma-suppression-obj

     object {
         string              ma-suppression-name;
        [ma-event-obj        ma-suppression-start;]
        [ma-event-obj        ma-suppression-end;]
        [string              ma-suppression-match<0..*>;]
        [boolean             ma-suppression-stop-running;]
     } ma-suppression-obj;

   The ma-suppression-obj controls the Suppression of Schedules or
   Actions and consists of the following elements:

   ma-suppression-name:          A name uniquely identifying a
                                 Suppression.

   ma-suppression-start:         The optional Event indicating when
                                 Suppression starts.  If not present,
                                 the Suppression starts immediately,
                                 i.e., as if the value would be
                                 'immediate'.

Top      ToC       Page 18 
   ma-suppression-end:           The optional Event indicating when
                                 Suppression ends.  If not present, the
                                 Suppression does not have a defined
                                 end, i.e., the Suppression remains for
                                 an indefinite period of time.

   ma-suppression-match:         An optional and possibly empty
                                 unordered set of match patterns.  The
                                 Suppression will apply to all Schedules
                                 (and their Actions) that have a
                                 matching value in their
                                 ma-schedule-suppression-tags and all
                                 Actions that have a matching value in
                                 their ma-action-suppression-tags.
                                 Pattern matching is done using a glob
                                 style pattern (see below).

   ma-suppression-stop-running:  An optional boolean indicating whether
                                 Suppression will stop any running
                                 matching Schedules or Actions.  The
                                 default value for this boolean is
                                 false.

   Glob style pattern matching is following POSIX.2 fnmatch() [POSIX.2]
   without special treatment of file paths:

               *         matches a sequence of characters
               ?         matches a single character
               [seq]     matches any character in seq
               [!seq]    matches any character not in seq

   A backslash followed by a character matches the following character.
   In particular:

               \*        matches *
               \?        matches ?
               \\        matches \

   A sequence seq may be a sequence of characters (e.g., [abc]) or a
   range of characters (e.g., [a-c]).


Next Section