GENWiki

Premier IT Outsourcing and Support Services within the UK

User Tools

Site Tools


rfc:rfc8193

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.

Burbridge, et al. Standards Track [Page 1] RFC 8193 LMAP Information Model August 2017

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

Burbridge, et al. Standards Track [Page 2] RFC 8193 LMAP Information Model August 2017

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

Burbridge, et al. Standards Track [Page 3] RFC 8193 LMAP Information Model August 2017

 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.

Burbridge, et al. Standards Track [Page 4] RFC 8193 LMAP Information Model August 2017

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.

Burbridge, et al. Standards Track [Page 5] RFC 8193 LMAP Information Model August 2017

 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.

Burbridge, et al. Standards Track [Page 6] RFC 8193 LMAP Information Model August 2017

 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.

Burbridge, et al. Standards Track [Page 7] RFC 8193 LMAP Information Model August 2017

 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.

Burbridge, et al. Standards Track [Page 8] RFC 8193 LMAP Information Model August 2017

      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.

Burbridge, et al. Standards Track [Page 9] RFC 8193 LMAP Information Model August 2017

 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.

Burbridge, et al. Standards Track [Page 10] RFC 8193 LMAP Information Model August 2017

 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.

Burbridge, et al. Standards Track [Page 11] RFC 8193 LMAP Information Model August 2017

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

Burbridge, et al. Standards Track [Page 12] RFC 8193 LMAP Information Model August 2017

 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.

Burbridge, et al. Standards Track [Page 13] RFC 8193 LMAP Information Model August 2017

 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

Burbridge, et al. Standards Track [Page 14] RFC 8193 LMAP Information Model August 2017

 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

Burbridge, et al. Standards Track [Page 15] RFC 8193 LMAP Information Model August 2017

 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.

Burbridge, et al. Standards Track [Page 16] RFC 8193 LMAP Information Model August 2017

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

Burbridge, et al. Standards Track [Page 17] RFC 8193 LMAP Information Model August 2017

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

Burbridge, et al. Standards Track [Page 18] RFC 8193 LMAP Information Model August 2017

4.4. Logging Information

 The MA may report on the success or failure of Configuration or
 Instruction communications from the Controller.  In addition, further
 operational logs may be produced during the operation of the MA, and
 updates to Capabilities may also be reported.  Reporting this
 information is achieved in exactly the same manner as scheduling any
 other Task.  We make no distinction between a Measurement Task
 conducting an active or passive network measurement and one that
 solely retrieves static or dynamic information from the MA such as
 Capabilities or Logging Information.  One or more logging Tasks can
 be programmed or configured to capture subsets of the Logging
 Information.  These logging Tasks are then executed by Schedules,
 which also specify that the resultant data is to be transferred over
 the Controller Channels.
 The type of Logging Information will fall into three different
 categories:
 1.  Success/failure/warning messages in response to information
     updates from the Controller.  Failure messages could be produced
     due to some inability to receive or parse the Controller
     communication or if the MA is not able to act as instructed.  For
     example:
  • "Measurement Schedules updated OK"
  • "Unable to parse JSON"
  • "Missing mandatory element: Measurement Timing"
  • "'Start' does not conform to schema - expected datetime"
  • "Date specified is in the past"
  • "'Hour' must be in the range 1..24"
  • "Schedule A refers to non-existent Measurement Task

Configuration"

  • "Measurement Task Configuration X registry, entry Y not found"
  • "Updated Measurement Task Configurations do not include M used

by Measurement Schedule N"

Burbridge, et al. Standards Track [Page 19] RFC 8193 LMAP Information Model August 2017

 2.  Operational updates from the MA.  For example:
  • "Out of memory: cannot record result"
  • "Collector 'collector.example.com' not responding"
  • "Unexpected restart"
  • "Suppression timeout"
  • "Failed to execute Measurement Task Configuration H"
 3.  Status updates from the MA.  For example:
  • "Device interface added: eth3"
  • "Supported measurements updated"
  • "New IP address on eth0: xxx.xxx.xxx.xxx"
 This Information Model document does not detail the precise format of
 Logging Information since it is to a large extent protocol and MA
 specific.  However, some common information can be identified.

4.4.1. Definition of ma-log-obj

   object {
       uuid                ma-log-agent-id;
       datetime            ma-log-event-time;
       int                 ma-log-code;
       string              ma-log-description;
   } ma-log-obj;
 The ma-log-obj models the generic aspects of a logging object and
 consists of the following elements:
 ma-log-agent-id:          A uuid uniquely identifying the Measurement
                           Agent.
 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.

Burbridge, et al. Standards Track [Page 20] RFC 8193 LMAP Information Model August 2017

4.5. Capability and Status Information

 The MA will hold Capability Information that can be retrieved by a
 Controller.  Capabilities include the device interface details
 available to Measurement Tasks as well as the set of Measurement
 Tasks/Roles (specified by registry entries) that are actually
 installed or available on the MA.  Status Information includes the
 times that operations were last performed such as contacting the
 Controller or producing Reports.

4.5.1. Definition of ma-capability-obj

   object {
       string                  ma-capability-hardware;
       string                  ma-capability-firmware;
       string                  ma-capability-version;
      [string                  ma-capability-tags<0..*>;]
      [ma-capability-task-obj  ma-capability-tasks<0..*>;]
   } ma-capability-obj;
 The ma-capability-obj provides information about the Capabilities of
 the Measurement Agent and consists of the following elements:
 ma-capability-hardware:   A description of the hardware of the device
                           the Measurement Agent is running on.
 ma-capability-firmware:   A description of the firmware of the device
                           the Measurement Agent is running on.
 ma-capability-version:    The version of the Measurement Agent.
 ma-capability-tags:       An optional unordered set of tags that
                           provide additional information about the
                           Capabilities of the Measurement Agent.
 ma-capability-tasks:      An optional unordered set of capability
                           objects for each supported Task.

4.5.2. Definition of ma-capability-task-obj

   object {
       string              ma-capability-task-name;
       ma-registry-obj     ma-capability-task-functions<0..*>;
       string              ma-capability-task-version;
   } ma-capability-task-obj;

Burbridge, et al. Standards Track [Page 21] RFC 8193 LMAP Information Model August 2017

 The ma-capability-task-obj provides information about the capability
 of a Task and consists of the following elements:
 ma-capability-task-name:        A name uniquely identifying a Task.
 ma-capability-task-functions:   A possibly empty unordered set of
                                 registry entries identifying
                                 functions this Task implements.
 ma-capability-task-version:     The version of the Measurement Task.

4.5.3. Definition of ma-status-obj

   object {
       uuid                       ma-status-agent-id;
      [uri                        ma-status-device-id;]
       datetime                   ma-status-last-started;
       ma-status-interface-obj    ma-status-interfaces<0..*>;
      [ma-status-schedule-obj     ma-status-schedules<0..*>;]
      [ma-status-suppression-obj  ma-status-suppressions<0..*>;]
   } ma-status-obj;
 The ma-status-obj provides Status Information about the Measurement
 Agent and consists of the following elements:
 ma-status-agent-id:       A uuid uniquely identifying the Measurement
                           Agent.
 ma-status-device-id:      A URI identifying the device.
 ma-status-last-started:   The date and time the Measurement Agent
                           last started.
 ma-status-interfaces:     An unordered set of network interfaces
                           available on the device.
 ma-status-schedules:      An optional unordered set of status objects
                           for each Schedule.
 ma-status-suppressions:   An optional unordered set of status objects
                           for each Suppression.

Burbridge, et al. Standards Track [Page 22] RFC 8193 LMAP Information Model August 2017

4.5.4. Definition of ma-status-schedule-obj

   object {
       string                  ma-status-schedule-name;
       string                  ma-status-schedule-state;
       int                     ma-status-schedule-storage;
       counter                 ma-status-schedule-invocations;
       counter                 ma-status-schedule-suppressions;
       counter                 ma-status-schedule-overlaps;
       counter                 ma-status-schedule-failures;
       datetime                ma-status-schedule-last-invocation;
      [ma-status-action-obj    ma-status-schedule-actions<0..*>;]
   } ma-status-schedule-obj;
 The ma-status-schedule-obj provides Status Information about the
 status of a Schedule and consists of the following elements:
 ma-status-schedule-name:            The name of the Schedule this
                                     status object refers to.
 ma-status-schedule-state:           The state of the Schedule.  The
                                     value 'enabled' indicates that
                                     the Schedule is currently
                                     enabled.  The value 'suppressed'
                                     indicates that the Schedule is
                                     currently suppressed.  The value
                                     'disabled' indicates that the
                                     Schedule is currently disabled.
                                     The value 'running' indicates
                                     that the Schedule is currently
                                     running.
 ma-status-schedule-storage:         The amount of secondary storage
                                     (e.g., allocated in a file
                                     system) holding temporary data
                                     allocated to the Schedule in
                                     bytes.  This object reports the
                                     amount of allocated physical
                                     storage and not the storage used
                                     by logical data records.  Data
                                     models should use a 64-bit
                                     integer type.

Burbridge, et al. Standards Track [Page 23] RFC 8193 LMAP Information Model August 2017

 ma-status-schedule-invocations      Number of invocations of this
                                     Schedule.  This counter does not
                                     include suppressed invocations or
                                     invocations that were prevented
                                     due to an overlap with a previous
                                     invocation of this Schedule.
 ma-status-schedule-suppressions     Number of suppressed executions
                                     of this Schedule.
 ma-status-schedule-overlaps         Number of executions prevented
                                     due to overlaps with a previous
                                     invocation of this Schedule.
 ma-status-schedule-failures         Number of failed executions of
                                     this Schedule.  A failed
                                     execution is an execution where
                                     at least one Action failed.
 ma-status-schedule-last-invocation: The date and time of the last
                                     invocation of this Schedule.
 ma-status-schedule-actions:         An optional ordered list of
                                     status objects for each Action of
                                     the Schedule.

4.5.5. Definition of ma-status-action-obj

   object {
       string              ma-status-action-name;
       string              ma-status-action-state;
       int                 ma-status-action-storage;
       counter             ma-status-action-invocations;
       counter             ma-status-action-suppressions;
       counter             ma-status-action-overlaps;
       counter             ma-status-action-failures;
       datetime            ma-status-action-last-invocation;
       datetime            ma-status-action-last-completion;
       int                 ma-status-action-last-status;
       string              ma-status-action-last-message;
       datetime            ma-status-action-last-failed-completion;
       int                 ma-status-action-last-failed-status;
       string              ma-status-action-last-failed-message;
   } ma-status-action-obj;

Burbridge, et al. Standards Track [Page 24] RFC 8193 LMAP Information Model August 2017

 The ma-status-action-obj provides Status Information about an Action
 of a Schedule and consists of the following elements:
 ma-status-action-name:                   The name of the Action of a
                                          Schedule this status object
                                          refers to.
 ma-status-action-state:                  The state of the Action.
                                          The value 'enabled'
                                          indicates that the Action is
                                          currently enabled.  The
                                          value 'suppressed' indicates
                                          that the Action is currently
                                          suppressed.  The value
                                          'disabled' indicates that
                                          the Action is currently
                                          disabled.  The value
                                          'running' indicates that the
                                          Action is currently running.
 ma-status-action-storage:                The amount of secondary
                                          storage (e.g., allocated in
                                          a file system) holding
                                          temporary data allocated to
                                          the Action in bytes.  This
                                          object reports the amount of
                                          allocated physical storage
                                          and not the storage used by
                                          logical data records.  Data
                                          models should use a 64-bit
                                          integer type.
 ma-status-action-invocations             Number of invocations of
                                          this Action.  This counter
                                          does not include suppressed
                                          invocations or invocations
                                          that were prevented due to
                                          an overlap with a previous
                                          invocation of this Action.
 ma-status-action-suppressions            Number of suppressed
                                          executions of this Action.
 ma-status-action-overlaps                Number of executions
                                          prevented due to overlaps
                                          with a previous invocation
                                          of this Action.

Burbridge, et al. Standards Track [Page 25] RFC 8193 LMAP Information Model August 2017

 ma-status-action-failures                Number of failed executions
                                          of this Action.
 ma-status-action-last-invocation:        The date and time of the
                                          last invocation of this
                                          Action.
 ma-status-action-last-completion:        The date and time of the
                                          last completion of this
                                          Action.
 ma-status-action-last-status:            The status code returned by
                                          the last execution of this
                                          Action.
 ma-status-action-last-message:           The status message produced
                                          by the last execution of
                                          this Action.
 ma-status-action-last-failed-completion: The date and time of the
                                          last failed completion of
                                          this Action.
 ma-status-action-last-failed-status:     The status code returned by
                                          the last failed execution of
                                          this Action.
 ma-status-action-last-failed-message:    The status message produced
                                          by the last failed execution
                                          of this Action.

4.5.6. Definition of ma-status-suppression-obj

   object {
       string                  ma-status-suppression-name;
       string                  ma-status-suppression-state;
   } ma-status-suppression-obj;
 The ma-status-suppression-obj provides Status Information about the
 status of a Suppression and consists of the following elements:
 ma-status-suppression-name:   The name of the Suppression this status
                               object refers to.

Burbridge, et al. Standards Track [Page 26] RFC 8193 LMAP Information Model August 2017

 ma-status-suppression-state:  The state of the Suppression.  The
                               value 'enabled' indicates that the
                               Suppression is currently enabled.  The
                               value 'active' indicates that the
                               Suppression is currently active.  The
                               value 'disabled' indicates that the
                               Suppression is currently disabled.

4.5.7. Definition of ma-status-interface-obj

   object {
       string              ma-status-interface-name;
       string              ma-status-interface-type;
      [int                 ma-status-interface-speed;]
      [string              ma-status-interface-link-layer-address;]
      [ip-address          ma-status-interface-ip-addresses<0..*>;]
      [ip-address          ma-status-interface-gateways<0..*>;]
      [ip-address          ma-status-interface-dns-servers<0..*>;]
   } ma-status-interface-obj;
 The ma-status-interface-obj provides Status Information about network
 interfaces and consists of the following elements:
 ma-status-interface-name:               A name uniquely identifying a
                                         network interface.
 ma-status-interface-type:               The type of the network
                                         interface.
 ma-status-interface-speed:              An optional indication of the
                                         speed of the interface
                                         (measured in bits per
                                         second).
 ma-status-interface-link-layer-address: An optional link-layer
                                         address of the interface.
 ma-status-interface-ip-addresses:       An optional ordered list of
                                         IP addresses assigned to the
                                         interface.
 ma-status-interface-gateways:           An optional ordered list of
                                         gateways assigned to the
                                         interface.
 ma-status-interface-dns-servers:        An optional ordered list of
                                         DNS servers assigned to the
                                         interface.

Burbridge, et al. Standards Track [Page 27] RFC 8193 LMAP Information Model August 2017

4.6. Reporting Information

 At a point in time specified by a Schedule, the MA will execute Tasks
 that communicate a set of measurement results to the Collector.
 These Reporting Tasks will be configured to transmit Task results
 over a specified Report Channel to a Collector.
 It should be noted that the output from Tasks does not need to be
 sent to communication Channels.  It can alternatively, or
 additionally, be sent to other Tasks on the MA.  This facilitates
 using a first Measurement Task to control the operation of a later
 Measurement Task (such as first probing available line speed and then
 adjusting the operation of a video testing measurement) and also to
 allow local processing of data to output alarms (e.g., when
 performance drops from earlier levels).  Of course, subsequent Tasks
 also include Tasks that implement the Reporting Protocol(s) and
 transfer data to one or more Collectors.
 The Report generated by a Reporting Task is structured hierarchically
 to avoid repetition of report header and Measurement Task
 Configuration information.  The report starts with the timestamp of
 the report generation on the MA and details about the MA including
 the optional Measurement Agent Identifier and Group-ID (controlled by
 the Configuration Information).
 Much of the report information is optional and will depend on the
 implementation of the Reporting Task and any parameters defined in
 the Task Configuration for the Reporting Task.  For example, some
 Reporting Tasks may choose not to include the Measurement Task
 Configuration or Action parameters, while others may do so dependent
 on the Controller setting a configurable parameter in the Task
 Configuration.
 It is possible for a Reporting Task to send just the report header
 (datetime and optional Agent Identifier and/or Group-ID) if no
 measurement data is available.  Whether to send such empty reports
 again is dependent on the implementation of the Reporting Task and
 potential Task Configuration parameter.
 The handling of measurement data on the MA before generating a Report
 and transfer from the MA to the Collector is dependent on the
 implementation of the device, MA, and/or scheduled Tasks and not
 defined by the LMAP standards.  Such decisions may include limits to
 the measurement data storage and what to do when such available
 storage becomes depleted.  It is generally suggested that
 implementations running out of storage stop executing new Measurement
 Tasks and retain old measurement data.

Burbridge, et al. Standards Track [Page 28] RFC 8193 LMAP Information Model August 2017

 No context information, such as line speed or broadband product are
 included within the report header information as this data is
 reported by individual Tasks at the time they execute.  Either a
 Measurement Task can report contextual parameters that are relevant
 to that particular measurement or specific Tasks can be used to
 gather a set of contextual and environmental data at certain times
 independent of the Reporting Schedule.
 After the report header information, the results are reported grouped
 according to different Measurement Task Configurations.  Each Task
 section optionally starts with replicating the Measurement Task
 Configuration information before the result headers (titles for data
 columns) and the result data rows.  The Options reported are those
 used for the scheduled execution of the Measurement Task and
 therefore include the Options specified in the Task Configuration as
 well as additional Options specified in the Action.  The Action
 Options are appended to the Task Configuration Options in exactly the
 same order as they were provided to the Task during execution.
 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
 considered in the data analysis.
 Some Measurement Tasks may optionally include an indication of the
 cross-traffic although the definition of cross-traffic is left up to
 each individual Measurement Task.  Some Measurement Tasks may also
 output other environmental measures in addition to cross-traffic such
 as CPU utilization or interface speed.
 Whereas the Configuration and Instruction Information represent
 information transmitted via the Control Protocol, the Report
 represents the information that is transmitted via the Report
 Protocol.  It is constructed at the time of sending a report and
 represents the inherent structure of the information that is sent to
 the Collector.

4.6.1. Definition of ma-report-obj

   object {
       datetime              ma-report-date;
      [uuid                  ma-report-agent-id;]
      [string                ma-report-group-id;]
      [string                ma-report-measurement-point;]
      [ma-report-result-obj  ma-report-results<0..*>;]
   } ma-report-obj;

Burbridge, et al. Standards Track [Page 29] RFC 8193 LMAP Information Model August 2017

 The ma-report-obj provides the metadata of a single report and
 consists of the following elements:
 ma-report-date:               The date and time when the report was
                               sent to a Collector.
 ma-report-agent-id:           An optional uuid uniquely identifying
                               the Measurement Agent.
 ma-report-group-id:           An optional identifier of the group of
                               Measurement Agents this Measurement
                               Agent belongs to.
 ma-report-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-report-results:            An optional and possibly empty
                               unordered set of result objects.

4.6.2. Definition of ma-report-result-obj

   object {
       string                  ma-report-result-schedule-name;
       string                  ma-report-result-action-name;
       string                  ma-report-result-task-name;
      [ma-option-obj           ma-report-result-options<0..*>;]
      [string                  ma-report-result-tags<0..*>;]
       datetime                ma-report-result-event-time;
       datetime                ma-report-result-start-time;
      [datetime                ma-report-result-end-time;]
      [string                  ma-report-result-cycle-number;]
       int                     ma-report-result-status;
      [ma-report-conflict-obj  ma-report-result-conflicts<0..*>;]
      [ma-report-table-obj     ma-report-result-tables<0..*>;]
   } ma-report-result-obj;
 The ma-report-result-obj provides the metadata of a result report of
 a single executed Action.  It consists of the following elements:
 ma-report-result-schedule-name: The name of the Schedule that
                                 produced the result.
 ma-report-result-action-name:   The name of the Action in the
                                 Schedule that produced the result.

Burbridge, et al. Standards Track [Page 30] RFC 8193 LMAP Information Model August 2017

 ma-report-result-task-name:     The name of the Task that produced
                                 the result.
 ma-report-result-options:       An optional ordered joined list of
                                 options provided by the Task object
                                 and the Action object when the Action
                                 was started.
 ma-report-result-tags:          An optional unordered set of tags.
                                 This is the joined set of tags
                                 provided by the Task object, Action
                                 object, and Schedule object when the
                                 Action was started.
 ma-report-result-event-time:    The date and time of the Event that
                                 triggered the Schedule of the Action
                                 that produced the reported result
                                 values.  The date and time does not
                                 include any added randomization.
 ma-report-result-start-time:    The date and time of the start of the
                                 Action that produced the reported
                                 result values.
 ma-report-result-end-time:      An optional date and time indicating
                                 when the Action finished.
 ma-report-result-cycle-number:  An optional cycle number derived from
                                 ma-report-result-event-time.  It is
                                 the time closest to
                                 ma-report-result-event-time that is a
                                 multiple of the
                                 ma-event-cycle-interval of the Event
                                 that triggered the execution of the
                                 Schedule.  The value is only present
                                 in an ma-report-result-obj if the
                                 Event that triggered the execution of
                                 the Schedule has a defined
                                 ma-event-cycle-interval.  The cycle
                                 number is represented in the format
                                 YYYYMMDD.HHMMSS where YYYY represents
                                 the year, MM the month (1..12), DD
                                 the day of the months (01..31), HH
                                 the hour (00..23), MM the minute
                                 (00..59), and SS the second (00..59).
                                 The cycle number is using Coordinated
                                 Universal Time (UTC).

Burbridge, et al. Standards Track [Page 31] RFC 8193 LMAP Information Model August 2017

 ma-report-result-status:        The status code returned by the
                                 execution of the Action.
 ma-report-result-conflicts:     A possibly empty set of conflict
                                 Actions that might have impacted the
                                 measurement results being reported.
 ma-report-result-tables:        An optional and possibly empty
                                 unordered set of result tables.

4.6.3. Definition of ma-report-conflict-obj

   object {
       string  ma-report-conflict-schedule-name;
       string  ma-report-conflict-action-name;
       string  ma-report-conflict-task-name;
   } ma-report-conflict-obj;
 The ma-report-conflict-obj provides the information about a
 conflicting Action that might have impacted the measurement results.
 It consists of the following elements:
 ma-report-result-schedule-name: The name of the Schedule that may
                                 have impacted the result.
 ma-report-result-action-name:   The name of the Action in the
                                 Schedule that may have impacted the
                                 result.
 ma-report-result-task-name:     The name of the Task that may have
                                 impacted the result.

4.6.4. Definition of ma-report-table-obj

   object {
      [ma-registry-obj     ma-report-table-functions<0..*>;]
      [string]             ma-report-table-column-labels<0..*>;]
      [ma-report-row-obj   ma-report-table-rows<0..*>;]
   } ma-report-table-obj;
 The ma-report-table-obj represents a result table and consists of the
 following elements:
 ma-report-table-functions:      An optional and possibly empty
                                 unordered set of registry entries
                                 identifying the functions for which
                                 results are reported.

Burbridge, et al. Standards Track [Page 32] RFC 8193 LMAP Information Model August 2017

 ma-report-table-column-labels:  An optional and possibly empty
                                 ordered list of column labels.
 ma-report-table-rows:           A possibly empty ordered list of
                                 result rows.

4.6.5. Definition of ma-report-row-obj

   object {
       data                ma-report-row-values<0..*>;
   } ma-report-row-obj;
 The ma-report-row-obj represents a result row and consists of the
 following elements:
 ma-report-row-values:     A possibly empty ordered list of result
                           values.  When present, it contains an
                           ordered list of values that align to the
                           set of column labels for the report.

4.7. Common Objects: Schedules

 A Schedule specifies the execution of a single or repeated series of
 Actions.  An Action extends a configured Task with additional
 specific parameters.  Each Schedule contains basically two elements:
 an ordered list of Actions to be executed and an Event object
 triggering the execution of the Schedule.  The Schedule states what
 Actions to run (with what configuration) and when to run the Actions.
 A Schedule may optionally have an Event that stops the execution of
 the Schedule or a maximum duration after which a Schedule is stopped.
 Multiple Actions contained as an ordered list of a single Measurement
 Schedule will be executed according to the execution mode of the
 Schedule.  In sequential mode, Actions will be executed sequentially
 and in parallel mode, all Actions will be executed concurrently.  In
 pipelined mode, data produced by one Action is passed to the
 subsequent Action.  Actions contained in different Schedules execute
 in parallel with such conflicts being reported in the Reporting
 Information where necessary.  If two or more Schedules have the same
 start time, then the two will execute in parallel.  There is no
 mechanism to prioritize one Schedule over another or to mutex
 scheduled Tasks.
 As well as specifying which Actions to execute, the Schedule also
 specifies how to link the data outputs from each Action to other
 Schedules.  Specifying this within the Schedule allows the highest
 level of flexibility since it is even possible to send the output
 from different executions of the same Task Configuration to different

Burbridge, et al. Standards Track [Page 33] RFC 8193 LMAP Information Model August 2017

 destinations.  A single Task producing multiple different outputs is
 expected to properly tag the different results.  An Action receiving
 the output can then filter the results based on the tag if necessary.
 For example, a Measurement Task might report routine results to a
 data Reporting Task in a Schedule that communicates hourly via the
 broadband interface, but it also outputs emergency conditions via an
 alarm Reporting Task in a different Schedule communicating
 immediately over a General Packet Radio Service (GPRS) Channel.  Note
 that Task-to-Task data transfer is always specified in association
 with the scheduled execution of the sending Task -- there is no need
 for a corresponding input specification for the receiving Task.
 While it is likely that an MA implementation will use a queue
 mechanism between the Schedules or Actions, this Information Model
 does not mandate or define a queue.  The Information Model, however,
 reports the storage allocated to Schedules and Actions so that
 storage usage can be monitored.  Furthermore, it is recommended that
 MA implementations by default retain old data and stop the execution
 of new Measurement Tasks if the MA runs out of storage capacity.
 When specifying the Task to execute within the Schedule, i.e.,
 creating an Action, it is possible to add to the Option parameters.
 This allows the Task Configuration to determine the common
 characteristics of a Task, while selected parameters (e.g., the test
 target URL) are defined within as Option parameters of the Action in
 the Schedule.  A single Task's Configuration can even be used
 multiple times in the same Schedule with different additional
 parameters.  This allows for efficiency in creating and transferring
 the Instruction.  Note that the semantics of what happens if an
 Option is defined multiple times (in either the Task Configuration,
 the Action, or both) is not standardized and will depend upon the
 Task.  For example, some Tasks may legitimately take multiple values
 for a single parameter.
 Where Options are specified in both the Action and the Task
 Configuration, the Action Options are appended to those specified in
 the Task Configuration.
 Example:  An Action of a Schedule references a single Measurement
    Task Configuration for measuring UDP latency.  It specifies that
    results are to be sent to a Schedule with a Reporting Action.
    This Reporting Task of the Reporting Action is executed by a
    separate Schedule that specifies that it should run hourly at 5
    minutes past the hour.  When run, this Reporting Action takes the
    data generated by the UDP latency Measurement Task as well as any
    other data to be included in the hourly report and transfers it to
    the Collector over the Report Channel specified within its own
    Schedule.

Burbridge, et al. Standards Track [Page 34] RFC 8193 LMAP Information Model August 2017

 Schedules and Actions may optionally also be given tags that are
 included in result reports sent to a Collector.  In addition,
 Schedules can be given Suppression tags that may be used to select
 Schedules and Actions for Suppression.

4.7.1. Definition of ma-schedule-obj

   object {
       string              ma-schedule-name;
       ma-event-obj        ma-schedule-start;
      [ma-event-obj        ma-schedule-end;]
      [int                 ma-schedule-duration;]
       ma-action-obj       ma-schedule-actions<0..*>;
       string              ma-schedule-execution-mode;
      [string              ma-schedule-tags<0..*>;]
      [string              ma-schedule-suppression-tags<0..*>;]
   } ma-schedule-obj;
 The ma-schedule-obj is the main scheduling object.  It consists of
 the following elements:
 ma-schedule-name:             A name uniquely identifying a
                               scheduling object.
 ma-schedule-start:            An Event object indicating when the
                               Schedule starts.
 ma-schedule-end:              An optional Event object controlling
                               the forceful termination of scheduled
                               Actions.  When the Event occurs, all
                               Actions of the Schedule will be forced
                               to terminate gracefully.
 ma-schedule-duration:         An optional duration in seconds for the
                               Schedule.  All Actions of the Schedule
                               will be forced to terminate gracefully
                               after the duration number of seconds
                               past the start of the Schedule.
 ma-schedule-actions:          A possibly empty ordered list of
                               Actions to invoke when the Schedule
                               starts.

Burbridge, et al. Standards Track [Page 35] RFC 8193 LMAP Information Model August 2017

 ma-schedule-execution-mode:   Indicates whether the Actions should be
                               executed sequentially, in parallel, or
                               in a pipelined mode (where data
                               produced by one Action is passed to the
                               subsequent Action).  The default
                               execution mode is pipelined.
 ma-schedule-tags:             An optional unordered set of tags that
                               are reported together with the
                               measurement results to a Collector.
 ma-schedule-suppression-tags: An optional unordered set of
                               Suppression tags that are used to
                               select Schedules to be suppressed.

4.7.2. Definition of ma-action-obj

   object {
       string              ma-action-name;
       string              ma-action-config-task-name;
      [ma-option-obj       ma-action-task-options<0..*>;]
      [string              ma-action-destinations<0..*>;]
      [string              ma-action-tags<0..*>;]
      [string              ma-action-suppression-tags<0..*>;]
    } ma-action-obj;
 The ma-action-obj models a Task together with its Schedule-specific
 Task Options and Destination Schedules.  It consists of the following
 elements:
 ma-action-name:               A name uniquely identifying an Action
                               of a scheduling object.
 ma-action-config-task-name:   A name identifying the configured Task
                               to be invoked by the Action.
 ma-action-task-options:       An optional and possibly empty ordered
                               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
                               unordered set of names of Destination
                               Schedules that consume output produced
                               by this Action.

Burbridge, et al. Standards Track [Page 36] RFC 8193 LMAP Information Model August 2017

 ma-action-tags:               An optional unordered set of tags that
                               are reported together with the
                               measurement results to a Collector.
 ma-action-suppression-tags:   An optional unordered set of
                               Suppression tags that are used to
                               select Actions to be suppressed.

4.8. Common Objects: Channels

 A Channel defines a bidirectional communication mechanism between the
 MA and a Controller or Collector.  Multiple Channels can be defined
 to enable results to be split or duplicated across different
 Collectors.
 Each Channel contains the details of the remote endpoint (including
 location and security credential information such as a certificate).
 The timing of when to communicate over a Channel is specified by the
 Schedule, which executes the corresponding Control or Reporting Task.
 The certificate can be the digital certificate associated to the
 Fully Qualified Domain Name (FQDN) in the URL, or it can be the
 certificate of the Certification Authority that was used to issue the
 certificate for the FQDN of the target URL (which will be retrieved
 later on using a communication protocol such as Transport Layer
 Security (TLS)).  In order to establish a secure Channel, the MA will
 use its own security credentials (in the Configuration Information)
 and the given credentials for the individual Channel endpoint.
 As with the Task Configurations, each Channel is also given a text
 name by which it can be referenced as a Task Option.
 Although the same in terms of information, Channels used for
 communication with the Controller are referred to as Control Channels
 whereas Channels to Collectors are referred to as Report Channels.
 Hence, Control Channels will be referenced from Control Tasks
 executed by a Control Schedule, whereas Report Channels will be
 referenced from within Reporting Tasks executed by an Instruction
 Schedule.
 Multiple interfaces are also supported.  For example, the Reporting
 Task could be configured to send some results over GPRS.  This is
 especially useful when such results indicate the loss of connectivity
 on a different network interface.
 Example:  A Channel used for reporting results may specify that
    results are to be sent to the URL (https://collector.example.org/
    report/), using the appropriate digital certificate to establish a
    secure Channel.

Burbridge, et al. Standards Track [Page 37] RFC 8193 LMAP Information Model August 2017

4.8.1. Definition of ma-channel-obj

   object {
       string              ma-channel-name;
       url                 ma-channel-target;
       credentials         ma-channel-credentials;
       [string             ma-channel-interface-name;]
   } ma-channel-obj;
 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 IP
                             protocol stack will select a suitable
                             interface.

4.9. Common Objects: Task Configurations

 Conceptually, each Task Configuration defines the parameters of a
 Task that the MA may perform at some point in time.  It does not by
 itself actually instruct the MA to perform them at any particular
 time (this is done by a Schedule).  Tasks can be Measurement Tasks
 (i.e., those Tasks actually performing some type of passive or active
 measurement) or any other scheduled activity performed by the MA such
 as transferring information to or from the Controller and Collectors.
 Other examples of Tasks may include data manipulation or processing
 Tasks conducted on the MA.
 A Measurement Task Configuration is the same in information terms to
 any other Task Configuration.  Both Measurement and non-Measurement
 Tasks may have registry entries to enable the MA to uniquely identify
 the Task it should execute and retrieve the schema for any parameters
 that may be passed to the Task.  Registry entries are specified as a
 URI and can therefore be used to identify the Task within a namespace
 or point to a web or local file location for the Task information.
 As mentioned previously, these URIs may be used to identify the
 Measurement Task in a public namespace such as the to-be-created IPPM
 registry described in [IPPM-REG].

Burbridge, et al. Standards Track [Page 38] RFC 8193 LMAP Information Model August 2017

 Example:  A Measurement Task Configuration may configure a single
    Measurement Task for measuring UDP latency.  The Measurement Task
    Configuration could define the destination port and address for
    the measurement as well as the duration, internal packet timing
    strategy, and other parameters (for example, a stream for one hour
    and sending one packet every 500 ms).  It may also define the
    output type and possible parameters (for example, the output type
    can be the 95th percentile mean) where the Measurement Task
    accepts such parameters.  It does not define when the Task starts
    (this is defined by the Schedule element), so it does not by
    itself instruct the MA to actually perform this Measurement Task.
 The Task Configuration will include a local short name for reference
 by a Schedule.  Task Configurations may also refer to registry
 entries as described above.  In addition, the Task can be configured
 through a set of configuration Options.  The nature and number of
 these Options will depend upon the Task.  These Options are expressed
 as name-value pairs, although the 'value' may be a structured object
 instead of a simple string or numeric value.  The implementation of
 these name-value pairs will vary between data models.
 An Option that must be present for Reporting Tasks is the Channel
 reference specifying how to communicate with a Collector.  This is
 included in the Task Options and will have a value that matches a
 Channel name that has been defined in the Instruction.  Similarly,
 Control Tasks will have a similar Option with the value set to a
 specified Control Channel.
 A Reporting Task might also have a flag parameter, defined as an
 Option, to indicate whether to send a report without measurement
 results if there is no measurement result data pending to be
 transferred to the Collector.  In addition, many Tasks will receive
 (as a parameter) information about which interface to use.
 In addition, the Task Configuration may optionally also be given tags
 that can carry a Measurement Cycle ID.  The purpose of this ID is to
 easily identify a set of measurement results that have been produced
 by Measurement Tasks with comparable Options.  This ID could be
 manually incremented or otherwise changed when an Option change is
 implemented, which could mean that two sets of results should not be
 directly compared.

Burbridge, et al. Standards Track [Page 39] RFC 8193 LMAP Information Model August 2017

4.9.1. Definition of ma-task-obj

   object {
       string              ma-task-name;
       ma-registry-obj     ma-task-functions<0..*>;
      [ma-option-obj       ma-task-options<0..*>;]
      [string              ma-task-tags<0..*>;]
   } ma-task-obj;
 The ma-task-obj defines a configured Task that can be invoked as part
 of an Action.  A configured Task can be referenced by its name, and
 it contains a possibly empty set of URIs to link to registry entries.
 Options allow the configuration of Task parameters (in the form of
 name-value pairs).  The ma-task-obj consists of the following
 elements:
 ma-task-name:             A name uniquely identifying a configured
                           Task object.
 ma-task-functions:        A possibly empty unordered set of registry
                           entries identifying the functions of the
                           configured Task.
 ma-task-options:          An optional and possibly empty ordered list
                           of options (name-value pairs) that are
                           passed to the configured Task.
 ma-task-tags:             An optional unordered set of tags that are
                           reported together with the measurement
                           results to a Collector.

4.9.2. Definition of ma-option-obj

   object {
       string              ma-option-name;
      [object              ma-option-value;]
   } ma-option-obj;
 The ma-option-obj models a name-value pair and consists of the
 following elements:
 ma-option-name:           The name of the option.
 ma-option-value:          The optional value of the option.
 The ma-option-obj is used to define Task Configuration Options.  Task
 Configuration Options are generally Task specific.  For Tasks
 associated with an entry in a registry, the registry may define well-

Burbridge, et al. Standards Track [Page 40] RFC 8193 LMAP Information Model August 2017

 known option names (e.g., the so-called parameters in the to-be-
 created IPPM metric registry described in [IPPM-REG]).  Control and
 Reporting Tasks need to know the Channel they are going to use.  The
 common option name for specifying the Channel is "channel" where the
 option's value refers to the name of an ma-channel-obj.

4.10. Common Objects: Registry Information

 Tasks and Actions can be associated with entries in a registry.  A
 registry object refers to an entry in a registry (identified by a
 URI), and it may define a set of roles.

4.10.1. Definition of ma-registry-obj

   object {
       uri                 ma-registry-uri;
      [string              ma-registry-role<0..*>;]
   } ma-registry-obj;
 The ma-registry-obj refers to an entry of a registry, and it defines
 the associated role(s).  The ma-registry-obj consists of the
 following elements:
 ma-registry-uri:          A URI identifying an entry in a registry.
 ma-registry-role:         An optional and possibly empty unordered
                           set of roles for the identified registry
                           entry.

4.11. Common Objects: Event Information

 The Event information object used throughout the Information Models
 can initially take one of several different forms.  Additional forms
 may be defined later in order to bind the execution of Schedules to
 additional Events.  The initially defined Event forms are:
 1.  Periodic Timing: Emits multiple Events periodically according to
     an interval time defined in seconds
 2.  Calendar Timing: Emits multiple Events according to a calendar-
     based pattern, e.g., 22 minutes past each hour of the day on
     weekdays
 3.  One-Off Timing: Emits one Event at a specific date and time
 4.  Immediate: Emits one Event as soon as possible

Burbridge, et al. Standards Track [Page 41] RFC 8193 LMAP Information Model August 2017

 5.  Startup: Emits an Event whenever the MA is started (e.g., at
     device startup)
 6.  Controller Lost: Emits an Event when connectivity to the
     Controller has been lost
 7.  Controller Connected: Emits an Event when connectivity to the
     Controller has been established or re-established
 Optionally, each of the Event options may also specify a randomness
 that should be evaluated and applied separately to each indicated
 Event.  This randomness parameter defines a uniform interval in
 seconds over which the start of the Task is delayed from the starting
 times specified by the Event object.
 Both the periodic and calendar timing objects allow for a series of
 Actions to be executed.  While both have an optional end time, it is
 best practice to always configure an end time and refresh the
 information periodically to ensure that lost MAs do not continue
 their Tasks forever.
 Startup Events are only created on device startup, not when a new
 Instruction is transferred to the MA.  If scheduled Task execution is
 desired both on the transfer of the Instruction and on device
 restart, then both the Immediate and Startup timing needs to be used
 in conjunction.
 The datetime format used for all elements in the Information Model
 MUST conform to RFC 3339 [RFC3339].

4.11.1. Definition of ma-event-obj

   object {
      string               ma-event-name;
      union {
          ma-periodic-obj             ma-event-periodic;
          ma-calendar-obj             ma-event-calendar;
          ma-one-off-obj              ma-event-one-off;
          ma-immediate-obj            ma-event-immediate;
          ma-startup-obj              ma-event-startup;
          ma-controller-lost-obj      ma-event-controller-lost;
          ma-controller-connected-obj ma-event-controller-connected;
      }
      [int                 ma-event-random-spread;]
      [int                 ma-event-cycle-interval;]
   } ma-event-obj;

Burbridge, et al. Standards Track [Page 42] RFC 8193 LMAP Information Model August 2017

 The ma-event-obj is the main Event object.  Event objects are
 identified by a name.  A generic Event object itself contains a more
 specific Event object.  The set of specific Event objects should be
 extensible.  The initial set of specific Event objects is further
 described below.  The ma-event-obj also includes an optional uniform
 random spread that can be used to randomize the start times of
 Schedules triggered by an Event.  The ma-event-obj consists of the
 following elements:
 ma-event-name:                  The name uniquely identifies an Event
                                 object.  Schedules refer to Event
                                 objects by this name.
 ma-event-periodic:              The ma-event-periodic is present for
                                 periodic timing objects.
 ma-event-calendar:              The ma-event-calendar is present for
                                 calendar timing objects.
 ma-event-one-off:               The ma-event-one-off is present for
                                 one-off timing objects.
 ma-event-immediate:             The ma-event-immediate is present for
                                 immediate Event objects.
 ma-event-startup:               The ma-event-startup is present for
                                 startup Event objects.
 ma-event-controller-lost:       The ma-event-controller-lost is
                                 present for connectivity to
                                 Controller lost Event objects.
 ma-event-controller-connected:  The ma-event-controller-connected is
                                 present for connectivity to
                                 Controller established Event objects.
 ma-event-random-spread:         The optional ma-event-random-spread
                                 adds a random delay defined in
                                 seconds to the Event object.  No
                                 random delay is added if
                                 ma-event-random-spread does not
                                 exist.

Burbridge, et al. Standards Track [Page 43] RFC 8193 LMAP Information Model August 2017

 ma-event-cycle-interval:        The optional ma-event-cycle-interval
                                 defines the duration of the time
                                 interval in seconds that is used to
                                 calculate cycle numbers.  No cycle
                                 number is calculated if
                                 ma-event-cycle-interval does not
                                 exist.

4.11.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.  Schedules 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
                           Schedules using this object are first
                           started.  If not present, it defaults to
                           immediate.
 ma-periodic-end:          The optional date and time at which
                           Schedules using this object are last
                           started.  If not present, it defaults to
                           indefinite.
 ma-periodic-interval:     The interval defines the time in seconds
                           between two consecutive starts of Tasks.

4.11.3. Definition of ma-calendar-obj

 Calendar timing supports the routine execution of Schedules at
 specific times and/or on specific dates.  It can support more
 flexible timing than periodic timing since the execution of Schedules
 does not have to be uniformly spaced.  For example, a calendar timing
 could support the execution of a Measurement Task every hour between
 6 pm and midnight on weekdays only.
 Calendar timing is also required to perform measurements at
 meaningful times in relation to network usage (e.g., at peak times).
 If the optional time zone offset is not supplied, then local system
 time is assumed.  This is essential in some use cases to ensure
 consistent peak-time measurements as well as supporting MA devices

Burbridge, et al. Standards Track [Page 44] RFC 8193 LMAP Information Model August 2017

 that may be in an unknown time zone or to roam between different time
 zones (but know their own time zone information such as through the
 mobile network).
 The calendar elements within the calendar timing do not have defaults
 in order to avoid accidental high-frequency execution of Tasks.  If
 all possible values for an element are desired, then the wildcard *
 is used.
   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;
 ma-calendar-start:            The optional date and time at which
                               Schedules using this object are first
                               started.  If not present, it defaults
                               to immediate.
 ma-calendar-end:              The optional date and time at which
                               Schedules using this object are last
                               started.  If not present, it defaults
                               to indefinite.
 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.
 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 the week.
                               If not present, it defaults to no days.

Burbridge, et al. Standards Track [Page 45] RFC 8193 LMAP Information Model August 2017

 ma-calendar-days-of-month:    The optional set of days of a month
                               (1-31) on which Tasks scheduled using
                               this object are started.  The wildcard
                               * means all days of a month.  If not
                               present, it defaults to no days.
 ma-calendar-hours:            The optional set of hours (0-23) on
                               which Tasks scheduled using this object
                               are started.  The wildcard * means all
                               hours of a day.  If not present, it
                               defaults to no hours.
 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 minutes.
 ma-calendar-seconds:          The optional set of seconds (0-59) on
                               which Tasks scheduled using this object
                               are started.  The wildcard * means all
                               seconds of an hour.  If not present, it
                               defaults to no seconds.
 ma-calendar-timezone-offset:  The optional time zone offset in
                               minutes.  If not present, it defaults
                               to the system's local time zone.
 If a day of the month is specified that does not exist in the month
 (e.g., the 29th of February), then those values are ignored.

4.11.4. Definition of ma-one-off-obj

   object {
       datetime            ma-one-off-time;
   } ma-one-off-obj;
 The ma-one-off-obj timing object specifies a fixed point in time.
 Schedules 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:
 ma-one-off-time:          The date and time at which Schedules using
                           this object are started.

Burbridge, et al. Standards Track [Page 46] RFC 8193 LMAP Information Model August 2017

4.11.5. Definition of ma-immediate-obj

   object {
                           // empty
   } ma-immediate-obj;
 The ma-immediate-obj Event object has no further information
 elements.  Schedules using an ma-immediate-obj are started as soon as
 possible.

4.11.6. Definition of ma-startup-obj

   object {
                           // empty
   } ma-startup-obj;
 The ma-startup-obj Event object has no further information elements.
 Schedules or Suppressions using an ma-startup-obj are started at MA
 initialization time.

4.11.7. Definition of ma-controller-lost-obj

   object {
                           // empty
   } ma-controller-lost-obj;
 The ma-controller-lost-obj Event object has no further information
 elements.  The ma-controller-lost-obj indicates that connectivity to
 the Controller has been lost.  This is determined by a timer started
 after each successful contact with a Controller.  When the timer
 reaches the controller-timeout (measured in seconds), a
 ma-controller-lost-obj Event is generated.  This Event may be used to
 start a Suppression.

4.11.8. Definition of ma-controller-connected-obj

   object {
                           // empty
   } ma-controller-connected-obj;
 The ma-controller-connected-obj Event object has no further
 information elements.  The ma-controller-connected-obj indicates that
 connectivity to the Controller has been established again after it
 was lost.  This Event may be used to end a Suppression.

Burbridge, et al. Standards Track [Page 47] RFC 8193 LMAP Information Model August 2017

5. Example Execution

 The example execution has two Event sources, E1 and E2, and three
 Schedules, S1, S2, and S3.  The Schedule S3 is started by Events of
 Event source E2 while the Schedules S1 and S2 are both started by
 Events of the Event source E1.  The Schedules S1 and S2 have two
 Actions each, and Schedule S3 has a single Action.  The Event source
 E2 has no randomization while the Event source E1 has the
 randomization r.
 Figure 2 shows a possible timeline of an execution.  The time T is
 progressing downwards.  The dotted vertical line indicates progress
 of time while a dotted horizontal line indicates which Schedules are
 triggered by an Event.  Lines of tildes indicate data flowing from an
 Action to another Schedule.  Actions within a Schedule are named A1,
 A2, etc.

Burbridge, et al. Standards Track [Page 48] RFC 8193 LMAP Information Model August 2017

   E2    E1   T           S1           S2            S3
                      sequential    parallel     pipelined
              :
           e0 +
              :
              :
         e0+r + .......... + .......... ++
              :            | A1      A1 || A2
              :            +            |+ ~~~~~~~>
              :            | A2         |
              :            |            + ~~~~~~~~>
              :            + ~~~~~~~~~~~~~~~~~~~~~>
              :
              :
           e1 +
              :
         e1+r + .......... + .......... ++
              :            | A1      A1 ||
              :            |            +|~~~~~~~>
              :            |             | A2
              :            +             +~~~~~~~>
              :            | A2
              :            + ~~~~~~~~~~~~~~~~~~~~>
    e0        + ................................... +
              :                                     | A1
           e3 +                                     |
         e3+r + .......... + .......... ++          |
              :            | A1      A1 || A2       |
              :            +            ++ ~~~~~~>  |
              :            | A2                     +
              :            + ~~~~~~~~~~~~~~~~~~~~>
              V
                      Figure 2: Example Execution
 Note that implementations must handle possible concurrency issues.
 In the example execution, Action A1 of Schedule S3 is consuming the
 data that has been forwarded to Schedule S3 while additional data is
 arriving from Action A2 of Schedule S2.

6. IANA Considerations

 This document does not require any IANA actions.

Burbridge, et al. Standards Track [Page 49] RFC 8193 LMAP Information Model August 2017

7. Security Considerations

 This Information Model deals with information about the control and
 reporting of the Measurement Agent.  There are broadly two security
 considerations for such an Information Model.  Firstly, the
 Information Model has to be sufficient to establish secure
 communication Channels to the Controller and Collector such that
 other information can be sent and received securely.  Additionally,
 any mechanisms that the Network Operator or other device
 administrator employs to preconfigure the MA must also be secure to
 protect unauthorized parties from modifying Preconfiguration
 Information.  These mechanisms are important to ensure that the MA
 cannot be hijacked, for example, to participate in a distributed
 denial-of-service attack.
 The second consideration is that no mandated information items should
 pose a risk to confidentiality or privacy given such secure
 communication Channels.  For this latter reason, items such as the MA
 context and MA-ID are left optional and can be excluded from some
 deployments.  This may, for example, allow the MA to remain anonymous
 and for information about location or other context that might be
 used to identify or track the MA to be omitted or blurred.
 Implementations and deployments should also be careful about exposing
 device-ids when this is not strictly needed.
 An implementation of this Information Model should support all the
 security and privacy requirements associated with the LMAP Framework
 [RFC7594].  In addition, users of this Information Model are advised
 to choose identifiers for Group-IDs, tags, or names of Information
 Model objects (e.g., configured Tasks, Schedules, or Actions) that do
 not reveal any sensitive information to people authorized to process
 measurement results but who are not authorized to know details about
 the Measurement Agents that were used to perform the measurement.

8. References

8.1. Normative References

 [ISO.10646]
            International Organization for Standardization,
            "Information Technology - Universal Coded Character Set
            (UCS)", ISO Standard 10646:2014, September 2014.
 [POSIX.2]  The Open Group, "Standard for Information Technology -
            Portable Operating System Interface (POSIX(R)) Base
            Specifications, Issue 7", IEEE Standard 1003.1, 2016
            Edition, DOI, 10.1109/IEEESTD.2016.7582338, September
            2016.

Burbridge, et al. Standards Track [Page 50] RFC 8193 LMAP Information Model August 2017

 [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
            Requirement Levels", BCP 14, RFC 2119,
            DOI 10.17487/RFC2119, March 1997,
            <https://www.rfc-editor.org/info/rfc2119>.
 [RFC3339]  Klyne, G. and C. Newman, "Date and Time on the Internet:
            Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
            <https://www.rfc-editor.org/info/rfc3339>.
 [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
            Resource Identifier (URI): Generic Syntax", STD 66,
            RFC 3986, DOI 10.17487/RFC3986, January 2005,
            <https://www.rfc-editor.org/info/rfc3986>.
 [RFC4122]  Leach, P., Mealling, M., and R. Salz, "A Universally
            Unique IDentifier (UUID) URN Namespace", RFC 4122,
            DOI 10.17487/RFC4122, July 2005,
            <https://www.rfc-editor.org/info/rfc4122>.
 [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
            2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
            May 2017, <https://www.rfc-editor.org/info/rfc8174>.

8.2. Informative References

 [IPPM-REG] Bagnulo, M., Claise, B., Eardley, P., Morton, A., and A.
            Akhter, "Registry for Performance Metrics", Work in
            Progress, draft-ietf-ippm-metric-registry-12, June 2017.
 [RFC3444]  Pras, A. and J. Schoenwaelder, "On the Difference between
            Information Models and Data Models", RFC 3444,
            DOI 10.17487/RFC3444, January 2003,
            <https://www.rfc-editor.org/info/rfc3444>.
 [RFC7398]  Bagnulo, M., Burbridge, T., Crawford, S., Eardley, P., and
            A. Morton, "A Reference Path and Measurement Points for
            Large-Scale Measurement of Broadband Performance",
            RFC 7398, DOI 10.17487/RFC7398, February 2015,
            <https://www.rfc-editor.org/info/rfc7398>.
 [RFC7536]  Linsner, M., Eardley, P., Burbridge, T., and F. Sorensen,
            "Large-Scale Broadband Measurement Use Cases", RFC 7536,
            DOI 10.17487/RFC7536, May 2015,
            <https://www.rfc-editor.org/info/rfc7536>.

Burbridge, et al. Standards Track [Page 51] RFC 8193 LMAP Information Model August 2017

 [RFC7594]  Eardley, P., Morton, A., Bagnulo, M., Burbridge, T.,
            Aitken, P., and A. Akhter, "A Framework for Large-Scale
            Measurement of Broadband Performance (LMAP)", RFC 7594,
            DOI 10.17487/RFC7594, September 2015,
            <https://www.rfc-editor.org/info/rfc7594>.
 [RFC8194]  Schoenwaelder, J. and V. Bajpai, "A YANG Data Model for
            LMAP Measurement Agents", RFC 8194, DOI 10.17487/RFC8194,
            August 2017, <http://www.rfc-editor.org/info/rfc8194>.

Acknowledgements

 Several people contributed to this specification by reviewing early
 draft versions and actively participating in the LMAP Working Group
 (apologies to those unintentionally omitted): Vaibhav Bajpai, Michael
 Bugenhagen, Timothy Carey, Alissa Cooper, Kenneth Ko, Al Morton, Dan
 Romascanu, Henning Schulzrinne, Andrea Soppera, Barbara Stark, and
 Jason Weil.
 Marcelo Bagnulo, Trevor Burbridge, Philip Eardley, and Juergen
 Schoenwaelder worked in part on the Leone research project, which
 received funding from the European Union Seventh Framework Programme
 [FP7/2007-2013] under grant agreement number 317647.
 Juergen Schoenwaelder was partly funded by Flamingo, a Network of
 Excellence project (ICT-318488) supported by the European Commission
 under its Seventh Framework Programme.

Burbridge, et al. Standards Track [Page 52] RFC 8193 LMAP Information Model August 2017

Authors' Addresses

 Trevor Burbridge
 BT
 Adastral Park, Martlesham Heath
 Ipswich  IP5 3RE
 United Kingdom
 Email: trevor.burbridge@bt.com
 Philip Eardley
 BT
 Adastral Park, Martlesham Heath
 Ipswich  IP5 3RE
 United Kingdom
 Email: philip.eardley@bt.com
 Marcelo Bagnulo
 Universidad Carlos III de Madrid
 Av. Universidad 30
 Leganes, Madrid  28911
 Spain
 Email: marcelo@it.uc3m.es
 Juergen Schoenwaelder
 Jacobs University Bremen
 Campus Ring 1
 Bremen  28759
 Germany
 Email: j.schoenwaelder@jacobs-university.de

Burbridge, et al. Standards Track [Page 53]

/data/webs/external/dokuwiki/data/pages/rfc/rfc8193.txt · Last modified: 2017/08/21 23:59 by 127.0.0.1

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki