Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 8193

Information Model for Large-Scale Measurement Platforms (LMAPs)

Pages: 53
Proposed Standard
Part 1 of 3 – Pages 1 to 18
None   None   Next

Top   ToC   RFC8193 - 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   RFC8193 - 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   RFC8193 - 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   RFC8193 - 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   RFC8193 - 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   RFC8193 - 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   RFC8193 - 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   RFC8193 - 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   RFC8193 - 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   RFC8193 - 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   RFC8193 - 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   RFC8193 - 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   RFC8193 - 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   RFC8193 - 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   RFC8193 - 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   RFC8193 - 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   RFC8193 - 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   RFC8193 - 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 page on part 2)

Next Section