idnits 2.17.00 (12 Aug 2021) /tmp/idnits20025/draft-ietf-lmap-information-model-17.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 758 has weird spacing: '...ion-obj ma-in...' == Line 947 has weird spacing: '...ask-obj ma-ca...' == Line 993 has weird spacing: '...ace-obj ma-...' == Line 995 has weird spacing: '...ion-obj ma-st...' == Line 1029 has weird spacing: '...ion-obj ma-...' == (7 more instances...) -- The document date (February 22, 2017) is 1913 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: draft-ietf-ippm-metric-registry has been published as RFC 8911 == Outdated reference: draft-ietf-lmap-yang has been published as RFC 8194 Summary: 0 errors (**), 0 flaws (~~), 10 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Burbridge 3 Internet-Draft P. Eardley 4 Intended status: Standards Track BT 5 Expires: August 26, 2017 M. Bagnulo 6 Universidad Carlos III de Madrid 7 J. Schoenwaelder 8 Jacobs University Bremen 9 February 22, 2017 11 Information Model for Large-Scale Measurement Platforms (LMAP) 12 draft-ietf-lmap-information-model-17 14 Abstract 16 This Information Model applies to the Measurement Agent within a 17 Large-Scale Measurement Platform. As such it outlines the 18 information that is (pre-)configured on the Measurement Agent or 19 exists in communications with a Controller or Collector within an 20 LMAP framework. The purpose of such an Information Model is to 21 provide a protocol and device independent view of the Measurement 22 Agent that can be implemented via one or more Control and Report 23 protocols. 25 Requirements Language 27 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 28 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 29 document are to be interpreted as described in RFC 2119 [RFC2119]. 31 Status of This Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at http://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on August 26, 2017. 48 Copyright Notice 50 Copyright (c) 2017 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents 55 (http://trustee.ietf.org/license-info) in effect on the date of 56 publication of this document. Please review these documents 57 carefully, as they describe your rights and restrictions with respect 58 to this document. Code Components extracted from this document must 59 include Simplified BSD License text as described in Section 4.e of 60 the Trust Legal Provisions and are provided without warranty as 61 described in the Simplified BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 66 2. Notation . . . . . . . . . . . . . . . . . . . . . . . . . . 5 67 3. LMAP Information Model . . . . . . . . . . . . . . . . . . . 6 68 3.1. Pre-Configuration Information . . . . . . . . . . . . . . 10 69 3.1.1. Definition of ma-preconfig-obj . . . . . . . . . . . 11 70 3.2. Configuration Information . . . . . . . . . . . . . . . . 11 71 3.2.1. Definition of ma-config-obj . . . . . . . . . . . . . 13 72 3.3. Instruction Information . . . . . . . . . . . . . . . . . 14 73 3.3.1. Definition of ma-instruction-obj . . . . . . . . . . 16 74 3.3.2. Definition of ma-suppression-obj . . . . . . . . . . 17 75 3.4. Logging Information . . . . . . . . . . . . . . . . . . . 18 76 3.4.1. Definition of ma-log-obj . . . . . . . . . . . . . . 20 77 3.5. Capability and Status Information . . . . . . . . . . . . 20 78 3.5.1. Definition of ma-capability-obj . . . . . . . . . . . 20 79 3.5.2. Definition of ma-capability-task-obj . . . . . . . . 21 80 3.5.3. Definition of ma-status-obj . . . . . . . . . . . . . 21 81 3.5.4. Definition of ma-status-schedule-obj . . . . . . . . 22 82 3.5.5. Definition of ma-status-action-obj . . . . . . . . . 23 83 3.5.6. Definition of ma-status-suppression-obj . . . . . . . 26 84 3.5.7. Definition of ma-status-interface-obj . . . . . . . . 26 85 3.6. Reporting Information . . . . . . . . . . . . . . . . . . 27 86 3.6.1. Definition of ma-report-obj . . . . . . . . . . . . . 29 87 3.6.2. Definition of ma-report-result-obj . . . . . . . . . 29 88 3.6.3. Definition of ma-report-conflict-obj . . . . . . . . 31 89 3.6.4. Definition of ma-report-table-obj . . . . . . . . . . 32 90 3.6.5. Definition of ma-report-row-obj . . . . . . . . . . . 32 91 3.7. Common Objects: Schedules . . . . . . . . . . . . . . . . 32 92 3.7.1. Definition of ma-schedule-obj . . . . . . . . . . . . 34 93 3.7.2. Definition of ma-action-obj . . . . . . . . . . . . . 35 94 3.8. Common Objects: Channels . . . . . . . . . . . . . . . . 36 95 3.8.1. Definition of ma-channel-obj . . . . . . . . . . . . 37 97 3.9. Common Objects: Task Configurations . . . . . . . . . . . 37 98 3.9.1. Definition of ma-task-obj . . . . . . . . . . . . . . 39 99 3.9.2. Definition of ma-option-obj . . . . . . . . . . . . . 39 100 3.10. Common Objects: Registry Information . . . . . . . . . . 40 101 3.10.1. Definition of ma-registry-obj . . . . . . . . . . . 40 102 3.11. Common Objects: Event Information . . . . . . . . . . . . 40 103 3.11.1. Definition of ma-event-obj . . . . . . . . . . . . . 41 104 3.11.2. Definition of ma-periodic-obj . . . . . . . . . . . 43 105 3.11.3. Definition of ma-calendar-obj . . . . . . . . . . . 43 106 3.11.4. Definition of ma-one-off-obj . . . . . . . . . . . . 45 107 3.11.5. Definition of ma-immediate-obj . . . . . . . . . . . 46 108 3.11.6. Definition of ma-startup-obj . . . . . . . . . . . . 46 109 3.11.7. Definition of ma-controller-lost-obj . . . . . . . . 46 110 3.11.8. Definition of ma-controller-connected-obj . . . . . 46 111 4. Example Execution . . . . . . . . . . . . . . . . . . . . . . 47 112 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48 113 6. Security Considerations . . . . . . . . . . . . . . . . . . . 49 114 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 49 115 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 50 116 8.1. Normative References . . . . . . . . . . . . . . . . . . 50 117 8.2. Informative References . . . . . . . . . . . . . . . . . 50 118 Appendix A. Change History . . . . . . . . . . . . . . . . . . . 51 119 A.1. Non-editorial changes since -16 . . . . . . . . . . . . . 51 120 A.2. Non-editorial changes since -15 . . . . . . . . . . . . . 51 121 A.3. Non-editorial changes since -14 . . . . . . . . . . . . . 51 122 A.4. Non-editorial changes since -13 . . . . . . . . . . . . . 51 123 A.5. Non-editorial changes since -12 . . . . . . . . . . . . . 51 124 A.6. Non-editorial changes since -11 . . . . . . . . . . . . . 52 125 A.7. Non-editorial changes since -10 . . . . . . . . . . . . . 52 126 A.8. Non-editorial changes since -09 . . . . . . . . . . . . . 52 127 A.9. Non-editorial changes since -08 . . . . . . . . . . . . . 52 128 A.10. Non-editorial changes since -07 . . . . . . . . . . . . . 53 129 A.11. Non-editorial changes since -06 . . . . . . . . . . . . . 53 130 A.12. Non-editorial changes since -05 . . . . . . . . . . . . . 54 131 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 54 133 1. Introduction 135 A large-scale measurement platform is a collection of components that 136 work in a coordinated fashion to perform measurements from a large 137 number of vantage points. The main components of a large-scale 138 measurement platform are the Measurement Agents (hereafter MAs), the 139 Controller(s) and the Collector(s). 141 The MAs are the elements actually performing the measurements. The 142 MAs are controlled by exactly one Controller at a time and the 143 Collectors gather the results generated by the MAs. In a nutshell, 144 the normal operation of a large-scale measurement platform starts 145 with the Controller instructing a set of one or more MAs to perform a 146 set of one or more Measurement Tasks at a certain point in time. The 147 MAs execute the instructions from a Controller, and once they have 148 done so, they report the results of the measurements to one or more 149 Collectors. The overall framework for a large-scale measurement 150 platform as used in this document is described in detail in 151 [RFC7594]. 153 A large-scale measurement platform involves basically three types of 154 protocols, namely, a Control protocol (or protocols) between a 155 Controller and the MAs, a Report protocol (or protocols) between the 156 MAs and the Collector(s) and several measurement protocols between 157 the MAs and Measurement Peers (MPs), used to actually perform the 158 measurements. In addition some information is required to be 159 configured on the MA prior to any communication with a Controller. 161 This document defines the information model for both Control and the 162 Report protocols along with pre-configuration information that is 163 required on the MA before communicating with the Controller, broadly 164 named as the LMAP Information Model. The measurement protocols are 165 out of the scope of this document. 167 As defined in [RFC3444], the LMAP Information Model defines the 168 concepts involved in a large-scale measurement platform at a high 169 level of abstraction, independent of any specific implementation or 170 actual protocol used to exchange the information. It is expected 171 that the proposed information model can be used with different 172 protocols in different measurement platform architectures and across 173 different types of MA devices (e.g., home gateway, smartphone, PC, 174 router). A YANG data model implementing the information model can be 175 found in [I-D.ietf-lmap-yang]. 177 The definition of an Information Model serves a number of purposes: 179 1. To guide the standardisation of one or more Control and Report 180 protocols and data models 182 2. To enable high-level inter-operability between different Control 183 and Report protocols by facilitating translation between their 184 respective data models such that a Controller could instruct sub- 185 populations of MAs using different protocols 187 3. To form agreement of what information needs to be held by an MA 188 and passed over the Control and Report interfaces and support the 189 functionality described in the LMAP framework 191 4. To enable existing protocols and data models to be assessed for 192 their suitability as part of a large-scale measurement system 194 2. Notation 196 This document uses a programming language-like notation to define the 197 properties of the objects of the information model. An optional 198 property is enclosed by square brackets, [ ], and a list property is 199 indicated by two numbers in angle brackets, , where m indicates 200 the minimal number of values, and n is the maximum. The symbol * for 201 n means no upper bound. 203 The object definitions use a couple of base types that are defined as 204 follows: 206 int A type representing signed or unsigned integer numbers. 207 This information model does not define a precision nor 208 does it make a distinction between signed and unsigned 209 number ranges. This type is also used to represent 210 enumerations. 212 boolean A type representing a boolean value. 214 string A type representing a human-readable string consisting of 215 a (possibly restricted) subset of Unicode and ISO/IEC 216 10646 [ISO.10646] characters. 218 datetime A type representing a date and time using the Gregorian 219 calendar. The datetime format MUST conform to RFC 3339 220 [RFC3339]. 222 uuid A type representing Universally Unique IDentifier (UUID( 223 as defined in RFC 4122 [RFC4122]. The UUID values are 224 expected to be unique within an installation of a large- 225 scale measurement system. 227 uri A type representing a Uniform Resource Identifier as 228 defined in STD 66 [RFC3986]. 230 ip-address A type representing an IP address. This type supports 231 both IPv4 and IPv6 addresses. 233 counter A non-negative integer that monotonically increases. 234 Counters may have discontinuities and they are not 235 expected to persist across restarts. 237 credentials An opaque type representing credentials needed by a 238 cryptographic mechanism to secure communication. Data 239 models must expand this opaque type as needed and 240 required by the security protocols utilized. 242 data An opaque type representing data obtained from 243 measurements. 245 Names of objects are generally assumed to be unique within an 246 implementation. 248 3. LMAP Information Model 250 The information described herein relates to the information stored, 251 received or transmitted by a Measurement Agent as described within 252 the LMAP framework [RFC7594]. As such, some subsets of this 253 information model are applicable to the measurement Controller, 254 Collector and any device management system that pre-configures the 255 Measurement Agent. The information described in these models will be 256 transmitted by protocols using interfaces between the Measurement 257 Agent and such systems according to a Data Model. 259 For clarity the information model is divided into six sections: 261 1. Pre-Configuration Information. Information pre-configured on the 262 Measurement Agent prior to any communication with other 263 components of the LMAP architecture (i.e., the Controller, 264 Collector and Measurement Peers), specifically detailing how to 265 communicate with a Controller and whether the device is enabled 266 to participate as an MA. 268 2. Configuration Information. Update of the pre-configuration 269 information during the registration of the MA or subsequent 270 communication with the Controller, along with the configuration 271 of further parameters about the MA (rather than the Measurement 272 Tasks it should perform) that were not mandatory for the initial 273 communication between the MA and a Controller. 275 3. Instruction Information. Information that is received by the MA 276 from the Controller pertaining to the Measurement Tasks that 277 should be executed. This includes the task execution Schedules 278 (other than the Controller communication Schedule supplied as 279 (pre)configuration information) and related information such as 280 the Task Configuration, communication Channels to Collectors and 281 schedule Event and Timing information. It also includes Task 282 Suppression information that is used to over-ride normal Task 283 execution. 285 4. Logging Information. Information transmitted from the MA to the 286 Controller detailing the results of any configuration operations 287 along with error and status information from the operation of the 288 MA. 290 5. Capability and Status Information. Information on the general 291 status and capabilities of the MA. For example, the set of 292 measurements that are supported on the device. 294 6. Reporting Information. Information transmitted from the MA to 295 one or more Collectors including measurement results and the 296 context in which they were conducted. 298 In addition the MA may hold further information not described herein, 299 and which may be optionally transferred to or from other systems 300 including the Controller and Collector. One example of information 301 in this category is subscriber or line information that may be 302 extracted by a task and reported by the MA in the reporting 303 communication to a Collector. 305 It should also be noted that the MA may be in communication with 306 other management systems which may be responsible for configuring and 307 retrieving information from the MA device. Such systems, where 308 available, can perform an important role in transferring the pre- 309 configuration information to the MA or enabling/disabling the 310 measurement functionality of the MA. 312 The Information Model is divided into sub-sections for a number of 313 reasons. Firstly the grouping of information facilitates reader 314 understanding. Secondly, the particular groupings chosen are 315 expected to map to different protocols or different transmissions 316 within those protocols. 318 The granularity of data transmitted in each operation of the Control 319 and Report Protocols is not dictated by the Information Model. For 320 example, the Instruction object may be delivered in a single 321 operation. Alternatively, Schedules and Task Configurations may be 322 separated or even each Schedule/Task Configuration may be delivered 323 individually. Similarly the Information Model does not dictate 324 whether data is read, write, or read/write. For example, some 325 Control Protocols may have the ability to read back Configuration and 326 Instruction information which have been previously set on the MA. 327 Lastly, while some protocols may simply overwrite information (for 328 example refreshing the entire Instruction Information), other 329 protocols may have the ability to update or delete selected items of 330 information. 332 The information in these six sections is captured by a number of 333 common information objects. These objects are also described later 334 in this document and comprise of: 336 a. Schedules. A set of Schedules tells the MA to execute Actions. 337 An Action of a Schedule leads to the execution of a Task. 339 Without a Schedule no Task (including measurements or reporting 340 or communicating with the Controller) is ever executed. 341 Schedules are used within the Instruction to specify what tasks 342 should be performed, when, and how to direct their results. A 343 Schedule is also used within the pre-Configuration and 344 Configuration information in order to execute the Task or Tasks 345 required to communicate with the Controller. A specific Schedule 346 can only be active once. Attempts to start a Schedule while the 347 same Schedule is still running will fail. 349 b. Channels. A set of Channel objects are used to communicate with 350 a number of endpoints (i.e., the Controller and Collectors). 351 Each Channel object contains the information required for the 352 communication with a single endpoint such as the target location 353 and security details. 355 c. Task Configurations. A set of Task Configurations is used to 356 configure the Tasks that are run by the MA. This includes the 357 registry entries for the Task and any configuration parameters, 358 represented as Task Options. Task Configurations are referenced 359 from a Schedule in order to specify what Tasks the MA should 360 execute. 362 d. Events. A set of Event objects that can be referenced from the 363 Schedules. Each Schedule always references exactly one Event 364 object that determines when the schedule is executed. An Event 365 object specifies either a singleton or series of events that 366 indicate when Tasks should be executed. A commonly used kind of 367 Event objects are Timing objects. For Event objects specifying a 368 series of events, it is generally a good idea to configure an end 369 time and to refresh the end time as needed to ensure that MAs 370 that loose connectivity to their controller do not continue 371 executing Schedules forever. 373 Figure 1 illustrates the structure in which these common information 374 objects are referenced. The references are achieved by each object 375 (Task Configuration, Event) being given a short textual name that is 376 used by other objects. The objects shown in parenthesis are part of 377 the internal object structure of a Schedule. Channels are not shown 378 in the diagram since they are only used as an option by selected Task 379 Configurations but are similarly referenced using a short text name. 381 Schedule 382 |-- triggered by --> Event 383 | 384 |-- executes --> Action 1 385 | |-- using --> Task Configuration 386 | | 387 | `-- feeding to --> Destination Schedule 388 : 389 : 390 `-- executes --> Action N 391 |-- using --> Task Configuration 392 | 393 `-- feeding to --> Destination Schedule 395 Figure 1: Relationship between Schedules, Events, Actions, Task 396 Configurations, and Destination Schedules 398 The primary function of an MA is to execute Schedules. A Schedule, 399 which is triggered by an Event, executes a number of Actions. An 400 Action refers to a Configured Task and it may feed results to a 401 Destination Schedule. Both, Actions and Configured Tasks can provide 402 parameters, represented as Action Options and Task Options. 404 Tasks can implement a variety of different functions. While in terms 405 of the Information Model, all Tasks have the same structure, it can 406 help conceptually to think of different Task categories: 408 1. Measurement Tasks measure some aspect of network performance or 409 traffic. They may also capture contextual information from the 410 MA device or network interfaces such as the device type or 411 interface speed. 413 2. Data Transfer Tasks support the communication with a Controller 414 and Collectors: 416 A. Reporting Tasks report the results of Measurement Tasks to 417 Collectors 419 B. Control Task(s) implement the Control Protocol and 420 communicate with the Controller. 422 3. Data Analysis Tasks can exist to analyse data from other 423 Measurement Tasks locally on the MA 425 4. Data Management Tasks may exist to clean-up, filter or compress 426 data on the MA such as Measurement Task results 428 Figure 1 indicates that Actions can produce data that is fed into 429 Destination Schedules. This can by used by Actions implementing 430 Measurement Tasks to feed measurement results to a Schedule that 431 triggers Actions implementing Reporting Tasks. Data fed to a 432 Destination Schedule is consumed by the first Action of the 433 Destination Schedule if the Destination Schedule is using sequential 434 or pipelined execution mode and it is consumed by all Actions of the 435 Destination Schedule if the Destination Schedule is using parallel 436 execution mode. 438 3.1. Pre-Configuration Information 440 This information is the minimal information that needs to be pre- 441 configured to the MA in order for it to successfully communicate with 442 a Controller during the registration process. Some of the Pre- 443 Configuration Information elements are repeated in the Configuration 444 Information in order to allow an LMAP Controller to update these 445 items. The pre-configuration information also contains some elements 446 that are not under the control of the LMAP framework (such as the 447 device identifier and device security credentials). 449 This Pre-Configuration Information needs to include a URL of the 450 initial Controller from where configuration information can be 451 communicated along with the security information required for the 452 communication including the certificate of the Controller (or the 453 certificate of the Certification Authority which was used to issue 454 the certificate for the Controller). All this is expressed as a 455 Channel. While multiple Channels may be provided in the Pre- 456 Configuration Information they must all be associated with a single 457 Controller (e.g., over different interfaces or network protocols). 459 Where the MA pulls information from the Controller, the Pre- 460 Configuration Information also needs to contain the timing of the 461 communication with the Controller as well as the nature of the 462 communication itself (such as the protocol and data to be 463 transferred). The timing is represented as an Event that invokes a 464 Schedule that executes the Task(s) responsible for communication with 465 the Controller. It is this Task (or Tasks) that implement the 466 Control protocol between the MA and the Controller and utilises the 467 Channel information. The Task(s) may take additional parameters, as 468 defined by a Task Configuration. 470 Even where information is pushed to the MA from the Controller 471 (rather than pulled by the MA), a Schedule still needs to be 472 supplied. In this case the Schedule will simply execute a Controller 473 listener Task when the MA is started. A Channel is still required 474 for the MA to establish secure communication with the Controller. 476 It can be seen that these Channels, Schedules and Task Configurations 477 for the initial MA-Controller communication are no different in terms 478 of the Information Model to any other Channel, Schedule or Task 479 Configuration that might execute a Measurement Task or report the 480 measurement results (as described later). 482 The MA may be pre-configured with an MA ID, or may use a Device ID in 483 the first Controller contact before it is assigned an MA ID. The 484 Device ID may be a MAC address or some other device identifier 485 expressed as a URI. If the MA ID is not provided at this stage then 486 it must be provided by the Controller during Configuration. 488 3.1.1. Definition of ma-preconfig-obj 490 object { 491 [uuid ma-preconfig-agent-id;] 492 ma-task-obj ma-preconfig-control-tasks<1..*>; 493 ma-channel-obj ma-preconfig-control-channels<1..*>; 494 ma-schedule-obj ma-preconfig-control-schedules<1..*>; 495 [uri ma-preconfig-device-id;] 496 credentials ma-preconfig-credentials; 497 } ma-preconfig-obj; 499 The ma-preconfig-obj describes information that needs to be available 500 to the MA in order to bootstrap communication with a Controller. The 501 ma-preconfig-obj consists of the following elements: 503 ma-preconfig-agent-id: An optional uuid uniquely identifying 504 the measurement agent. 506 ma-preconfig-control-tasks: An unordered set of task objects. 508 ma-preconfig-control-channels: An unordered set of channel objects. 510 ma-preconfig-control-schedules: An unordered set of scheduling 511 objects. 513 ma-preconfig-device-id: An optional identifier for the 514 device. 516 ma-preconfig-credentials: The security credentials used by the 517 measurement agent. 519 3.2. Configuration Information 521 During registration or at any later point at which the MA contacts 522 the Controller (or vice-versa), the choice of Controller, details for 523 the timing of communication with the Controller or parameters for the 524 communication Task(s) can be changed (as captured by the Channels, 525 Schedules and Task Configurations objects). For example the pre- 526 configured Controller (specified as a Channel or Channels) may be 527 over-ridden with a specific Controller that is more appropriate to 528 the MA device type, location or characteristics of the network (e.g., 529 access technology type or broadband product). The initial 530 communication Schedule may be over-ridden with one more relevant to 531 routine communications between the MA and the Controller. 533 While some Control protocols may only use a single Schedule, other 534 protocols may use several Schedules (and related data transfer Tasks) 535 to update the Configuration Information, transfer the Instruction 536 Information, transfer Capability and Status Information and send 537 other information to the Controller such as log or error 538 notifications. Multiple Channels may be used to communicate with the 539 same Controller over multiple interfaces (e.g., to send logging 540 information over a different network). 542 In addition the MA will be given further items of information that 543 relate specifically to the MA rather than the measurements it is to 544 conduct or how to report results. The assignment of an ID to the MA 545 is mandatory. If the MA Agent ID was not optionally provided during 546 the pre-configuration then one must be provided by the Controller 547 during Configuration. Optionally a Group ID may also be given which 548 identifies a group of interest to which that MA belongs. For example 549 the group could represent an ISP, broadband product, technology, 550 market classification, geographic region, or a combination of 551 multiple such characteristics. Additional flags control whether the 552 MA ID or the Group ID are included in Reports. The reporting of a 553 Group ID without the MA ID may allow the MA to remain anonymous, 554 which may be particularly useful to prevent tracking of mobile MA 555 devices. 557 Optionally an MA can also be configured to stop executing any 558 Instruction Schedule if the Controller is unreachable. This can be 559 used as a fail-safe to stop Measurement and other Tasks being 560 conducted when there is doubt that the Instruction Information is 561 still valid. This is simply represented as a time window in seconds 562 since the last communication with the Controller after which an Event 563 is generated that can trigger the suspension of Instruction 564 Schedules. The appropriate value of the time window will depend on 565 the specified communication Schedule with the Controller and the 566 duration for which the system is willing to tolerate continued 567 operation with potentially stale Instruction Information. 569 While Pre-Configuration Information is persistent upon device reset 570 or power cycle, the persistency of the Configuration Information may 571 be device dependent. Some devices may revert back to their pre- 572 configuration state upon reboot or factory reset, while other devices 573 may store all Configuration and Instruction information in persistent 574 storage. A Controller can check whether an MA has the latest 575 Configuration and Instruction information by examining the Capability 576 and Status information for the MA. 578 3.2.1. Definition of ma-config-obj 580 object { 581 uuid ma-config-agent-id; 582 ma-task-obj ma-config-control-tasks<1..*>; 583 ma-channel-obj ma-config-control-channels<1..*>; 584 ma-schedule-obj ma-config-control-schedules<1..*>; 585 credentials ma-config-credentials; 586 [string ma-config-group-id;] 587 [string ma-config-measurement-point;] 588 [boolean ma-config-report-agent-id;] 589 [boolean ma-config-report-group-id;] 590 [boolean ma-config-report-measurement-point;] 591 [int ma-config-controller-timeout;] 592 } ma-config-obj; 594 The ma-config-obj consists of the following elements: 596 ma-config-agent-id: A uuid uniquely identifying the 597 measurement agent. 599 ma-config-control-tasks: An unordered set of task objects. 601 ma-config-control-channels: An unordered set of channel 602 objects. 604 ma-config-control-schedules: An unordered set of scheduling 605 objects. 607 ma-config-credentials: The security credentials used by 608 the measurement agent. 610 ma-config-group-id: An optional identifier of the 611 group of measurement agents this 612 measurement agent belongs to. 614 ma-config-measurement-point: An optional identifier for the 615 measurement point indicating 616 where the measurement agent is 617 located on a path (see [RFC7398] 618 for further details). 620 ma-config-report-agent-id: An optional flag indicating 621 whether the agent identifier (ma- 622 config-agent-id) is included in 623 reports. The default value is 624 true. 626 ma-config-report-group-id: An optional flag indicating 627 whether the group identifier (ma- 628 config-group-id) is included in 629 reports. The default value is 630 false. 632 ma-config-report-measurement-point: An optional flag indicating 633 whether the measurement point 634 (ma-config-measurement-point) 635 should be included in reports. 636 The default value is false. 638 ma-config-controller-timeout: A timer is started after each 639 successful contact with a 640 controller. When the timer 641 reaches the controller-timeout 642 (measured in seconds), an event 643 is raised indicating that 644 connectivity to the controller 645 has been lost (see ma-controller- 646 lost-obj). 648 3.3. Instruction Information 650 The Instruction information model has four sub-elements: 652 1. Instruction Task Configurations 654 2. Report Channels 656 3. Instruction Schedules 658 4. Suppression 660 The Instruction supports the execution of all Tasks on the MA except 661 those that deal with communication with the Controller (specified in 662 (pre-)configuration information). The Tasks are configured in 663 Instruction Task Configurations and included by reference in the 664 Actions of Instruction Schedules that specify when to execute them. 665 The results can be communicated to other Schedules or a Task may 666 implement a Reporting Protocol and communicate results over Report 667 Channels. Suppression is used to temporarily stop the execution of 668 new Tasks as specified by the Instruction Schedules (and optionally 669 to stop ongoing Tasks). 671 A Task Configuration is used to configure the mandatory and optional 672 parameters of a Task. It also serves to instruct the MA about the 673 Task including the ability to resolve the Task to an executable and 674 specifying the schema for the Task parameters. 676 A Report Channel defines how to communicate with a single remote 677 system specified by a URL. A Report Channel is used to send results 678 to a single Collector but is no different in terms of the Information 679 Model to the Control Channel used to transfer information between the 680 MA and the Controller. Several Report Channels can be defined to 681 enable results to be split or duplicated across different 682 destinations. A single Channel can be used by multiple (reporting) 683 Task Configurations to transfer data to the same Collector. A single 684 Reporting Task Configuration can also be included in multiple 685 Schedules. E.g., a single Collector may receive data at three 686 different cycle rates, one Schedule reporting hourly, another 687 reporting daily and a third specifying that results should be sent 688 immediately for on-demand measurement tasks. Alternatively multiple 689 Report Channels can be used to send Measurement Task results to 690 different Collectors. The details of the Channel element is 691 described later as it is common to several objects. 693 Instruction Schedules specify which Actions to execute according to a 694 given triggering Event. An Action extends a Configured Task with 695 additional specific parameters. An Event can trigger the execution 696 of a single Action or it can trigger a repeated series of Actions. 697 The Schedule also specifies how to link Tasks output data to other 698 Schedules. 700 Measurement Suppression information is used to over-ride the 701 Instruction Schedule and temporarily stop measurements or other Tasks 702 from running on the MA for a defined or indefinite period. While 703 conceptually measurements can be stopped by simply removing them from 704 the Measurement Schedule, splitting out separate information on 705 Measurement Suppression allows this information to be updated on the 706 MA on a different timing cycle or protocol implementation to the 707 Measurement Schedule. It is also considered that it will be easier 708 for a human operator to implement a temporary explicit suppression 709 rather than having to move to a reduced Schedule and then roll-back 710 at a later time. 712 It should be noted that control schedules and tasks cannot be 713 suppressed as evidenced by the lack of suppression information in the 714 Configuration. The control schedule must only reference tasks listed 715 as control tasks (i.e., within the Configuration information). 717 A single Suppression object is able to enable/disable a set of 718 Instruction Tasks that are tagged for suppression. This enables fine 719 grained control on which Tasks are suppressed. Suppression of both 720 matching Actions and Measurement Schedules is supported. Support for 721 disabling specific Actions allows malfunctioning or mis-configured 722 Tasks or Actions that have an impact on a particular part of the 723 network infrastructure (e.g., a particular Measurement Peer) to be 724 targeted. Support for disabling specific Schedules allows for 725 particularly heavy cycles or sets of less essential Measurement Tasks 726 to be suppressed quickly and effectively. Note that Suppression has 727 no effect on either Controller Tasks or Controller Schedules. 729 Suppression stops new Tasks from executing. In addition, the 730 Suppression information also supports an additional Boolean that is 731 used to select whether on-going tasks are also to be terminated. 733 Unsuppression is achieved through either overwriting the Measurement 734 Suppression information (e.g., changing 'enabled' to False) or 735 through the use of an End time such that the Measurement Suppression 736 will no longer be in effect beyond this time. 738 The goal when defining these four different elements is to allow each 739 part of the information model to change without affecting the other 740 three elements. For example it is envisaged that the Report Channels 741 and the set of Task Configurations will be relatively static. The 742 Instruction Schedule, on the other hand, is likely to be more 743 dynamic, as the measurement panel and test frequency are changed for 744 various business goals. Another example is that measurements can be 745 suppressed with a Suppression command without removing the existing 746 Instruction Schedules that would continue to apply after the 747 Suppression expires or is removed. In terms of the Controller-MA 748 communication this can reduce the data overhead. It also encourages 749 the re-use of the same standard Task Configurations and Reporting 750 Channels to help ensure consistency and reduce errors. 752 3.3.1. Definition of ma-instruction-obj 754 object { 755 ma-task-obj ma-instruction-tasks<0..*>; 756 ma-channel-obj ma-instruction-channels<0..*>; 757 ma-schedule-obj ma-instruction-schedules<0..*>; 758 [ma-suppression-obj ma-instruction-suppressions<0..*>;] 759 } ma-instruction-obj; 761 An ma-instruction-obj consists of the following elements: 763 ma-instruction-tasks: A possibly empty unordered set of task 764 objects. 766 ma-instruction-channels: A possibly empty unordered set of 767 channel objects. 769 ma-instruction-schedules: A possibly empty unordered set of 770 schedule objects. 772 ma-instruction-suppressions: An optional possibly empty unordered 773 set of suppression objects. 775 3.3.2. Definition of ma-suppression-obj 777 object { 778 string ma-suppression-name; 779 [ma-event-obj ma-suppression-start;] 780 [ma-event-obj ma-suppression-end;] 781 [string ma-suppression-match<0..*>;] 782 [boolean ma-suppression-stop-running;] 783 } ma-suppression-obj; 785 The ma-suppression-obj controls the suppression of schedules or 786 actions and consists of the following elements: 788 ma-suppression-name: A name uniquely identifying a 789 suppression. 791 ma-suppression-start: The optional event indicating when 792 suppression starts. If not present, 793 the suppression starts immediately, 794 i.e., as if the value would be 795 'immediate'. 797 ma-suppression-end: The optional event indicating when 798 suppression ends. If not present, the 799 suppression does not have a defined 800 end, i.e., the suppression remains for 801 an indefinite period of time. 803 ma-suppression-match: An optional and possibly empty 804 unordered set of match patterns. The 805 suppression will apply to all schedules 806 (and their actions) that have a 807 matching value in their ma-schedule- 808 suppression-tags and all actions that 809 have a matching value in their ma- 810 action-suppression-tags. Pattern 811 matching is done using glob style 812 pattern (see below). 814 ma-suppression-stop-running: An optional boolean indicating whether 815 suppression will stop any running 816 matching schedules or actions. The 817 default value for this boolean is 818 false. 820 Glob style pattern matching is following POSIX.2 fnmatch() [POSIX.2] 821 without special treatment of file paths: 823 * matches a sequence of characters 824 ? matches a single character 825 [seq] matches any character in seq 826 [!seq] matches any character not in seq 828 A backslash followed by a character matches the following character. 829 In particular: 831 \* matches * 832 \? matches ? 833 \\ matches \ 835 A sequence seq may be a sequence of characters (e.g., [abc] or a 836 range of characters (e.g., [a-c]). 838 3.4. Logging Information 840 The MA may report on the success or failure of Configuration or 841 Instruction communications from the Controller. In addition further 842 operational logs may be produced during the operation of the MA and 843 updates to capabilities may also be reported. Reporting this 844 information is achieved in exactly the same manner as scheduling any 845 other Task. We make no distinction between a Measurement Task 846 conducting an active or passive network measurement and one which 847 solely retrieves static or dynamic information from the MA such as 848 capabilities or logging information. One or more logging tasks can 849 be programmed or configured to capture subsets of the Logging 850 Information. These logging tasks are then executed by Schedules 851 which also specify that the resultant data is to be transferred over 852 the Controller Channels. 854 The type of Logging Information will fall into three different 855 categories: 857 1. Success/failure/warning messages in response to information 858 updates from the Controller. Failure messages could be produced 859 due to some inability to receive or parse the Controller 860 communication, or if the MA is not able to act as instructed. 861 For example: 863 * "Measurement Schedules updated OK" 865 * "Unable to parse JSON" 867 * "Missing mandatory element: Measurement Timing" 869 * "'Start' does not conform to schema - expected datetime" 871 * "Date specified is in the past" 873 * "'Hour' must be in the range 1..24" 875 * "Schedule A refers to non-existent Measurement Task 876 Configuration" 878 * "Measurement Task Configuration X registry entry Y not found" 880 * "Updated Measurement Task Configurations do not include M used 881 by Measurement Schedule N" 883 2. Operational updates from the MA. For example: 885 * "Out of memory: cannot record result" 887 * "Collector 'collector.example.com' not responding" 889 * "Unexpected restart" 891 * "Suppression timeout" 893 * "Failed to execute Measurement Task Configuration H" 895 3. Status updates from the MA. For example: 897 * "Device interface added: eth3" 899 * "Supported measurements updated" 901 * "New IP address on eth0: xxx.xxx.xxx.xxx" 903 This Information Model document does not detail the precise format of 904 logging information since it is to a large extent protocol and MA 905 specific. However, some common information can be identified. 907 3.4.1. Definition of ma-log-obj 909 object { 910 uuid ma-log-agent-id; 911 datetime ma-log-event-time; 912 int ma-log-code; 913 string ma-log-description; 914 } ma-log-obj; 916 The ma-log-obj models the generic aspects of a logging object and 917 consists of the following elements: 919 ma-log-agent-id: A uuid uniquely identifying the measurement 920 agent. 922 ma-log-event-time: The date and time of the event reported in 923 the logging object. 925 ma-log-code: A machine readable code describing the 926 event. 928 ma-log-description: A human readable description of the event. 930 3.5. Capability and Status Information 932 The MA will hold Capability Information that can be retrieved by a 933 Controller. Capabilities include the device interface details 934 available to Measurement Tasks as well as the set of Measurement 935 Tasks/Roles (specified by registry entries) that are actually 936 installed or available on the MA. Status information includes the 937 times that operations were last performed such as contacting the 938 Controller or producing Reports. 940 3.5.1. Definition of ma-capability-obj 942 object { 943 string ma-capability-hardware; 944 string ma-capability-firmware; 945 string ma-capability-version; 946 [string ma-capability-tags<0..*>;] 947 [ma-capability-task-obj ma-capability-tasks<0..*>;] 948 } ma-capability-obj; 950 The ma-capability-obj provides information about the capabilities of 951 the measurement agent and consists of the following elements: 953 ma-capability-hardware: A description of the hardware of the device 954 the measurement agent is running on. 956 ma-capability-firmware: A description of the firmware of the device 957 the measurement agent is running on. 959 ma-capability-version: The version of the measurement agent. 961 ma-capability-tags: An optional unordered set of tags that 962 provide additional information about the 963 capabilities of the measurement agent. 965 ma-capability-tasks: An optional unordered set of capability 966 objects for each supported task. 968 3.5.2. Definition of ma-capability-task-obj 970 object { 971 string ma-capability-task-name; 972 ma-registry-obj ma-capability-task-functions<0..*>; 973 string ma-capability-task-version; 974 } ma-capability-task-obj; 976 The ma-capability-task-obj provides information about the capability 977 of a task and consists of the following elements: 979 ma-capability-task-name: A name uniquely identifying a task. 981 ma-capability-task-functions: A possibly empty unordered set of 982 registry entries identifying 983 functions this task implements. 985 ma-capability-task-version: The version of the measurement task. 987 3.5.3. Definition of ma-status-obj 989 object { 990 uuid ma-status-agent-id; 991 [uri ma-status-device-id;] 992 datetime ma-status-last-started; 993 ma-status-interface-obj ma-status-interfaces<0..*>; 994 [ma-status-schedule-obj ma-status-schedules<0..*>;] 995 [ma-status-suppression-obj ma-status-suppressions<0..*>;] 996 } ma-status-obj; 998 The ma-status-obj provides status information about the measurement 999 agent and consists of the following elements: 1001 ma-status-agent-id: A uuid uniquely identifying the measurement 1002 agent. 1004 ma-status-device-id: A URI identifying the device. 1006 ma-status-last-started: The date and time the measurement agent 1007 last started. 1009 ma-status-interfaces: An unordered set of network interfaces 1010 available on the device. 1012 ma-status-schedules: An optional unordered set of status objects 1013 for each schedule. 1015 ma-status-suppressions: An optional unordered set of status objects 1016 for each suppression. 1018 3.5.4. Definition of ma-status-schedule-obj 1020 object { 1021 string ma-status-schedule-name; 1022 string ma-status-schedule-state; 1023 int ma-status-schedule-storage; 1024 counter ma-status-schedule-invocations; 1025 counter ma-status-schedule-suppressions; 1026 counter ma-status-schedule-overlaps; 1027 counter ma-status-schedule-failures; 1028 datetime ma-status-schedule-last-invocation; 1029 [ma-status-action-obj ma-status-schedule-actions<0..*>;] 1030 } ma-status-schedule-obj; 1032 The ma-status-schedule-obj provides status information about the 1033 status of a schedule and consists of the following elements: 1035 ma-status-schedule-name: The name of the schedule this 1036 status object refers to. 1038 ma-status-schedule-state: The state of the schedule. The 1039 value 'enabled' indicates that 1040 the schedule is currently 1041 enabled. The value 'suppressed' 1042 indicates that the schedule is 1043 currently suppressed. The value 1044 'disabled' indicates that the 1045 schedule is currently disabled. 1046 The value 'running' indicates 1047 that the schedule is currently 1048 running. 1050 ma-status-schedule-storage: The amount of secondary storage 1051 (e.g., allocated in a file 1052 system) holding temporary data 1053 allocated to the schedule in 1054 bytes. This object reports the 1055 amount of allocated physical 1056 storage and not the storage used 1057 by logical data records. Data 1058 models should use a 64-bit 1059 integer type. 1061 ma-status-schedule-invocations Number of invocations of this 1062 schedule. This counter does not 1063 include suppressed invocations or 1064 invocations that were prevented 1065 due to an overlap with a previous 1066 invocation of this schedule. 1068 ma-status-schedule-suppressions Number of suppressed executions 1069 of this schedule. 1071 ma-status-schedule-overlaps Number of executions prevented 1072 due to overlaps with a previous 1073 invocation of this schedule. 1075 ma-status-schedule-failures Number of failed executions of 1076 this schedule. A failed 1077 execution is an execution where 1078 at least one action failed. 1080 ma-status-schedule-last-invocation: The date and time of the last 1081 invocation of this schedule. 1083 ma-status-schedule-actions: An optional ordered list of 1084 status objects for each action of 1085 the schedule. 1087 3.5.5. Definition of ma-status-action-obj 1088 object { 1089 string ma-status-action-name; 1090 string ma-status-action-state; 1091 int ma-status-action-storage; 1092 counter ma-status-action-invocations; 1093 counter ma-status-action-suppressions; 1094 counter ma-status-action-overlaps; 1095 counter ma-status-action-failures; 1096 datetime ma-status-action-last-invocation; 1097 datetime ma-status-action-last-completion; 1098 int ma-status-action-last-status; 1099 string ma-status-action-last-message; 1100 datetime ma-status-action-last-failed-completion; 1101 int ma-status-action-last-failed-status; 1102 string ma-status-action-last-failed-message; 1103 } ma-status-action-obj; 1105 The ma-status-action-obj provides status information about an action 1106 of a schedule and consists of the following elements: 1108 ma-status-action-name: The name of the action of a 1109 schedule this status object 1110 refers to. 1112 ma-status-action-state: The state of the action. 1113 The value 'enabled' 1114 indicates that the action is 1115 currently enabled. The 1116 value 'suppressed' indicates 1117 that the action is currently 1118 suppressed. The value 1119 'disabled' indicates that 1120 the action is currently 1121 disabled. The value 1122 'running' indicates that the 1123 action is currently running. 1125 ma-status-action-storage: The amount of secondary 1126 storage (e.g., allocated in 1127 a file system) holding 1128 temporary data allocated to 1129 the action in bytes. This 1130 object reports the amount of 1131 allocated physical storage 1132 and not the storage used by 1133 logical data records. Data 1134 models should use a 64-bit 1135 integer type. 1137 ma-status-action-invocations Number of invocations of 1138 this action. This counter 1139 does not include suppressed 1140 invocations or invocations 1141 that were prevented due to 1142 an overlap with a previous 1143 invocation of this action. 1145 ma-status-action-suppressions Number of suppressed 1146 executions of this action. 1148 ma-status-action-overlaps Number of executions 1149 prevented due to overlaps 1150 with a previous invocation 1151 of this action. 1153 ma-status-action-failures Number of failed executions 1154 of this action. 1156 ma-status-action-last-invocation: The date and time of the 1157 last invocation of this 1158 action. 1160 ma-status-action-last-completion: The date and time of the 1161 last completion of this 1162 action. 1164 ma-status-action-last-status: The status code returned by 1165 the last execution of this 1166 action. 1168 ma-status-action-last-message: The status message produced 1169 by the last execution of 1170 this action. 1172 ma-status-action-last-failed-completion: The date and time of the 1173 last failed completion of 1174 this action. 1176 ma-status-action-last-failed-status: The status code returned by 1177 the last failed execution of 1178 this action. 1180 ma-status-action-last-failed-message: The status message produced 1181 by the last failed execution 1182 of this action. 1184 3.5.6. Definition of ma-status-suppression-obj 1186 object { 1187 string ma-status-suppression-name; 1188 string ma-status-suppression-state; 1189 } ma-status-suppression-obj; 1191 The ma-status-suppression-obj provides status information about that 1192 status of a suppression and consists of the following elements: 1194 ma-status-suppression-name: The name of the suppression this status 1195 object refers to. 1197 ma-status-suppression-state: The state of the suppression. The 1198 value 'enabled' indicates that the 1199 suppression is currently enabled. The 1200 value 'active indicates that the 1201 suppression is currently active. The 1202 value 'disabled' indicates that the 1203 suppression is currently disabled. 1205 3.5.7. Definition of ma-status-interface-obj 1207 object { 1208 string ma-status-interface-name; 1209 string ma-status-interface-type; 1210 [int ma-status-interface-speed;] 1211 [string ma-status-interface-link-layer-address;] 1212 [ip-address ma-status-interface-ip-addresses<0..*>;] 1213 [ip-address ma-status-interface-gateways<0..*>;] 1214 [ip-address ma-status-interface-dns-servers<0..*>;] 1215 } ma-status-interface-obj; 1217 The ma-status-interface-obj provides status information about network 1218 interfaces and consists of the following elements: 1220 ma-status-interface-name: A name uniquely identifying a 1221 network interface. 1223 ma-status-interface-type: The type of the network 1224 interface. 1226 ma-status-interface-speed: An optional indication of the 1227 speed of the interface 1228 (measured in bits-per- 1229 second). 1231 ma-status-interface-link-layer-address: An optional link-layer 1232 address of the interface. 1234 ma-status-interface-ip-addresses: An optional ordered list of 1235 IP addresses assigned to the 1236 interface. 1238 ma-status-interface-gateways: An optional ordered list of 1239 gateways assigned to the 1240 interface. 1242 ma-status-interface-dns-servers: An optional ordered list of 1243 DNS servers assigned to the 1244 interface. 1246 3.6. Reporting Information 1248 At a point in time specified by a Schedule, the MA will execute tasks 1249 that communicate a set of measurement results to the Collector. 1250 These Reporting Tasks will be configured to transmit task results 1251 over a specified Report Channel to a Collector. 1253 It should be noted that the output from Tasks does not need to be 1254 sent to communication Channels. It can alternatively, or 1255 additionally, be sent to other Tasks on the MA. This facilitates 1256 using a first Measurement Task to control the operation of a later 1257 Measurement Task (such as first probing available line speed and then 1258 adjusting the operation of a video testing measurement) and also to 1259 allow local processing of data to output alarms (e.g., when 1260 performance drops from earlier levels). Of course, subsequent Tasks 1261 also include Tasks that implement the reporting protocol(s) and 1262 transfer data to one or more Collector(s). 1264 The Report generated by a Reporting Task is structured hierarchically 1265 to avoid repetition of report header and Measurement Task 1266 Configuration information. The report starts with the timestamp of 1267 the report generation on the MA and details about the MA including 1268 the optional Measurement Agent ID and Group ID (controlled by the 1269 Configuration Information). 1271 Much of the report Information is optional and will depend on the 1272 implementation of the Reporting Task and any parameters defined in 1273 the Task Configuration for the Reporting Task. For example some 1274 Reporting Tasks may choose not to include the Measurement Task 1275 Configuration or Action parameters, while others may do so dependent 1276 on the Controller setting a configurable parameter in the Task 1277 Configuration. 1279 It is possible for a Reporting Task to send just the Report header 1280 (datetime and optional agent ID and/or Group ID) if no measurement 1281 data is available. Whether to send such empty reports again is 1282 dependent on the implementation of the Reporting Task and potential 1283 Task Configuration parameter. 1285 The handling of measurement data on the MA before generating a Report 1286 and transfer from the MA to the Collector is dependent on the 1287 implementation of the device, MA and/or scheduled Tasks and not 1288 defined by the LMAP standards. Such decisions may include limits to 1289 the measurement data storage and what to do when such available 1290 storage becomes depleted. It is generally suggested that 1291 implementations running out of storage stop executing new measurement 1292 tasks and retain old measurement data. 1294 No context information, such as line speed or broadband product are 1295 included within the report header information as this data is 1296 reported by individual tasks at the time they execute. Either a 1297 Measurement Task can report contextual parameters that are relevant 1298 to that particular measurement, or specific tasks can be used to 1299 gather a set of contextual and environmental data at certain times 1300 independent of the reporting schedule. 1302 After the report header information the results are reported grouped 1303 according to different Measurement Task Configurations. Each Task 1304 section optionally starts with replicating the Measurement Task 1305 Configuration information before the result headers (titles for data 1306 columns) and the result data rows. The Options reported are those 1307 used for the scheduled execution of the Measurement Task and 1308 therefore include the Options specified in the Task Configuration as 1309 well as additional Options specified in the Action. The Action 1310 Options are appended to the Task Configuration Options in exactly the 1311 same order as they were provided to the Task during execution. 1313 The result row data includes a time for the start of the measurement 1314 and optionally an end time where the duration also needs to be 1315 considered in the data analysis. 1317 Some Measurement Tasks may optionally include an indication of the 1318 cross-traffic although the definition of cross-traffic is left up to 1319 each individual Measurement Task. Some Measurement Tasks may also 1320 output other environmental measures in addition to cross-traffic such 1321 as CPU utlilisation or interface speed. 1323 Whereas the Configuration and Instruction information represent 1324 information transmitted via the Control Protocol, the Report 1325 represents the information that is transmitted via the Report 1326 Protocol. It is constructed at the time of sending a report and 1327 represents the inherent structure of the information that is sent to 1328 the Collector. 1330 3.6.1. Definition of ma-report-obj 1332 object { 1333 datetime ma-report-date; 1334 [uuid ma-report-agent-id;] 1335 [string ma-report-group-id;] 1336 [string ma-report-measurement-point;] 1337 [ma-report-result-obj ma-report-results<0..*>;] 1338 } ma-report-obj; 1340 The ma-report-obj provides the meta-data of a single report and 1341 consists of the following elements: 1343 ma-report-date: The date and time when the report was 1344 sent to a collector. 1346 ma-report-agent-id: An optional uuid uniquely identifying 1347 the measurement agent. 1349 ma-report-group-id: An optional identifier of the group of 1350 measurement agents this measurement 1351 agent belongs to. 1353 ma-report-measurement-point: An optional identifier for the 1354 measurement point indicating where the 1355 measurement agent is located on a path 1356 (see [RFC7398] for further details). 1358 ma-report-results: An optional and possibly empty 1359 unordered set of result objects. 1361 3.6.2. Definition of ma-report-result-obj 1362 object { 1363 string ma-report-result-schedule-name; 1364 string ma-report-result-action-name; 1365 string ma-report-result-task-name; 1366 [ma-option-obj ma-report-result-options<0..*>;] 1367 [string ma-report-result-tags<0..*>;] 1368 datetime ma-report-result-event-time; 1369 datetime ma-report-result-start-time; 1370 [datetime ma-report-result-end-time;] 1371 [string ma-report-result-cycle-number;] 1372 int ma-report-result-status; 1373 [ma-report-conflict-obj ma-report-result-conflicts<0..*>;] 1374 [ma-report-table-obj ma-report-result-tables<0..*>;] 1375 } ma-report-result-obj; 1377 The ma-report-result-obj provides the meta-data of a result report of 1378 a single executed action. It consists of the following elements: 1380 ma-report-result-schedule-name: The name of the schedule that 1381 produced the result. 1383 ma-report-result-action-name: The name of the action in the 1384 schedule that produced the result. 1386 ma-report-result-task-name: The name of the task that produced 1387 the result. 1389 ma-report-result-options: An optional ordered joined list of 1390 options provided by the task object 1391 and the action object when the action 1392 was started. 1394 ma-report-result-tags: An optional unordered set of tags. 1395 This is the joined set of tags 1396 provided by the task object and the 1397 action object and schedule object 1398 when the action was started. 1400 ma-report-result-event-time: The date and time of the event that 1401 triggered the schedule of the action 1402 that produced the reported result 1403 values. The date and time does not 1404 include any added randomization. 1406 ma-report-result-start-time: The date and time of the start of the 1407 action that produced the reported 1408 result values. 1410 ma-report-result-end-time: An optional date and time indicating 1411 when the action finished. 1413 ma-report-result-cycle-number: An optional cycle number derived from 1414 ma-report-result-event-time. It is 1415 the time closest to ma-report-result- 1416 event-time that is a multiple of the 1417 ma-event-cycle-interval of the event 1418 that triggered the execution of the 1419 schedule. The value is only present 1420 in an ma-report-result-obj if the 1421 event that triggered the execution of 1422 the schedule has a defined ma-event- 1423 cycle-interval. The cycle number is 1424 represented in the format 1425 YYYYMMDD.HHMMSS where YYYY represents 1426 the year, MM the month (1..12), DD 1427 the day of the months (01..31), HH 1428 the hour (00..23), MM the minute 1429 (00..59), and SS the second (00..59). 1430 The cycle number is using Coordinated 1431 Universal Time (UTC). 1433 ma-report-result-status: The status code returned by the 1434 execution of the action. 1436 ma-report-result-conflicts: A possibly empty set of conflict 1437 actions that might have impacted the 1438 measurement results being reported. 1440 ma-report-result-tables: An optional and possibly empty 1441 unordered set of result tables. 1443 3.6.3. Definition of ma-report-conflict-obj 1445 object { 1446 string ma-report-conflict-schedule-name; 1447 string ma-report-conflict-action-name; 1448 string ma-report-conflict-task-name; 1449 } ma-report-conflict-obj; 1451 The ma-report-conflict-obj provides the information about conflicting 1452 action that might have impacted the measurement results. It consists 1453 of the following elements: 1455 ma-report-result-schedule-name: The name of the schedule that may 1456 have impacted the result. 1458 ma-report-result-action-name: The name of the action in the 1459 schedule that may have impacted the 1460 result. 1462 ma-report-result-task-name: The name of the task that may have 1463 impacted the result. 1465 3.6.4. Definition of ma-report-table-obj 1467 object { 1468 [ma-registry-obj ma-report-table-functions<0..*>;] 1469 [string] ma-report-table-column-labels<0..*>;] 1470 [ma-report-row-obj ma-report-table-rows<0..*>;] 1471 } ma-report-table-obj; 1473 The ma-report-table-obj represents a result table and consists of the 1474 following elements: 1476 ma-report-table-functions: An optional and possibly empty 1477 unordered set of registry entries 1478 identifying the functions for which 1479 results that are reported. 1481 ma-report-table-column-labels: An optional and possibly empty 1482 ordered list of column labels. 1484 ma-report-table-rows: A possibly empty ordered list of 1485 result rows. 1487 3.6.5. Definition of ma-report-row-obj 1489 object { 1490 data ma-report-row-values<0..*>; 1491 } ma-report-row-obj; 1493 The ma-report-row-obj represents a result row and consists of the 1494 following elements: 1496 ma-report-row-values: A possibly empty ordered list of result 1497 values. When present, it contains an 1498 ordered list of values that align to the 1499 set of column labels for the report. 1501 3.7. Common Objects: Schedules 1503 A Schedule specifies the execution of a single or repeated series of 1504 Actions. An Action extends a Configured Task with additional 1505 specific parameters. Each Schedule contains basically two elements: 1507 an ordered list of Actions to be executed and an Event object 1508 triggering the execution of the Schedule. The Schedule states what 1509 Actions to run (with what configuration) and when to run the Actions. 1510 A Schedule may optionally have an Event that stops the execution of 1511 the Schedule or a maximum duration after which a schedule is stopped. 1513 Multiple Actions contained as an ordered list of a single Measurement 1514 Schedule will be executed according to the execution mode of the 1515 Schedule. In sequential mode, Actions will be executed sequentially 1516 and in parallel mode, all Actions will be executed concurrently. In 1517 pipelined mode, data produced by one Action is passed to the 1518 subsequent Action. Actions contained in different Schedules execute 1519 in parallel with such conflicts being reported in the Reporting 1520 Information where necessary. If two or more Schedules have the same 1521 start time, then the two will execute in parallel. There is no 1522 mechanism to prioritise one schedule over another or to mutex 1523 scheduled tasks. 1525 As well as specifying which Actions to execute, the Schedule also 1526 specifies how to link the data outputs from each Action to other 1527 Schedules. Specifying this within the Schedule allows the highest 1528 level of flexibility since it is even possible to send the output 1529 from different executions of the same Task Configuration to different 1530 destinations. A single Task producing multiple different outputs is 1531 expected to properly tag the different result. An Action receiving 1532 the output can then filter the results based on the tag if necessary. 1533 For example, a Measurement Task might report routine results to a 1534 data Reporting Task in a Schedule that communicates hourly via the 1535 Broadband PPP interface, but also outputs emergency conditions via an 1536 alarm Reporting Task in a different Schedule communicating 1537 immediately over a GPRS channel. Note that task-to-task data 1538 transfer is always specified in association with the scheduled 1539 execution of the sending task - there is no need for a corresponding 1540 input specification for the receiving task. While it is likely that 1541 an MA implementation will use a queue mechanism between the Schedules 1542 or Actions, this Information Model does not mandate or define a 1543 queue. The Information Model, however, reports the storage allocated 1544 to Schedules and Actions so that storage usage can be monitored. 1545 Furthermore, it is recommended that MA implementations by default 1546 retain old data and stop the execution of new measurement tasks if 1547 the MA runs out of storage capacity. 1549 When specifying the task to execute within the Schedule, i.e., 1550 creating an Action, it is possible to add to the Action option 1551 parameters. This allows the Task Configuration to determine the 1552 common characteristics of a Task, while selected parameters (e.g., 1553 the test target URL) are defined within as option parameters of the 1554 Action in the schedule. A single Tasks Configuration can even be 1555 used multiple times in the same schedule with different additional 1556 parameters. This allows for efficiency in creating and transferring 1557 the Instruction. Note that the semantics of what happens if an 1558 option is defined multiple times (either in the Task Configuration, 1559 Action or in both) is not standardised and will depend upon the Task. 1560 For example, some tasks may legitimately take multiple values for a 1561 single parameter. 1563 Where Options are specified in both the Action and the Task 1564 Configuration, the Action Options are appended to those specified in 1565 the Task Configuration. 1567 Example: An Action of a Schedule references a single Measurement 1568 Task Configuration for measuring UDP latency. It specifies that 1569 results are to be sent to a Schedule with a Reporting Action. 1570 This Reporting Task of the Reporting Action is executed by a 1571 separate Schedule that specifies that it should run hourly at 5 1572 minutes past the hour. When run this Reporting Action takes the 1573 data generated by the UDP latency Measurement Task as well as any 1574 other data to be included in the hourly report and transfers it to 1575 the Collector over the Report Channel specified within its own 1576 Schedule. 1578 Schedules and Actions may optionally also be given tags that are 1579 included in result reports sent to a Collector. In addition, 1580 schedules can be given suppression tags that may be used to select 1581 Schedules and Actions for suppression. 1583 3.7.1. Definition of ma-schedule-obj 1585 object { 1586 string ma-schedule-name; 1587 ma-event-obj ma-schedule-start; 1588 [ma-event-obj ma-schedule-end;] 1589 [int ma-schedule-duration;] 1590 ma-action-obj ma-schedule-actions<0..*>; 1591 string ma-schedule-execution-mode; 1592 [string ma-schedule-tags<0..*>;] 1593 [string ma-schedule-suppression-tags<0..*>;] 1594 } ma-schedule-obj; 1596 The ma-schedule-obj is the main scheduling object. It consists of 1597 the following elements: 1599 ma-schedule-name: A name uniquely identifying a 1600 scheduling object. 1602 ma-schedule-start: An event object indicating when the 1603 schedule starts. 1605 ma-schedule-end: An optional event object controlling 1606 the forceful termination of scheduled 1607 actions. When the event occurs, all 1608 actions of the schedule will be forced 1609 to terminate gracefully. 1611 ma-schedule-duration: An optional duration in seconds for the 1612 schedule. All actions of the schedule 1613 will be forced to terminate gracefully 1614 after the duration number of seconds 1615 past the start of the schedule. 1617 ma-schedule-actions: A possibly empty ordered list of 1618 actions to invoke when the schedule 1619 starts. 1621 ma-schedule-execution-mode: Indicates whether the actions should be 1622 executed sequentially, in parallel, or 1623 in a pipelined mode (where data 1624 produced by one action is passed to the 1625 subsequent action). The default 1626 execution mode is pipelined. 1628 ma-schedule-tags: An optional unordered set of tags that 1629 are reported together with the 1630 measurement results to a collector. 1632 ma-schedule-suppression-tags: An optional unordered set of 1633 suppression tags that are used to 1634 select schedules to be suppressed. 1636 3.7.2. Definition of ma-action-obj 1638 object { 1639 string ma-action-name; 1640 string ma-action-config-task-name; 1641 [ma-option-obj ma-action-task-options<0..*>;] 1642 [string ma-action-destinations<0..*>;] 1643 [string ma-action-tags<0..*>;] 1644 [string ma-action-suppression-tags<0..*>;] 1645 } ma-action-obj; 1647 The ma-action-obj models a task together with its schedule specific 1648 task options and destination schedules. It consists of the following 1649 elements: 1651 ma-action-name: A name uniquely identifying an action 1652 of a scheduling object. 1654 ma-action-config-task-name: A name identifying the configured task 1655 to be invoked by the action. 1657 ma-action-task-options: An optional and possibly empty ordered 1658 list of options (name-value pairs) that 1659 are passed to the task by appending 1660 them to the options configured for the 1661 task object. 1663 ma-action-destinations: An optional and possibly empty 1664 unordered set of names of destination 1665 schedules that consume output produced 1666 by this action. 1668 ma-action-tags: An optional unordered set of tags that 1669 are reported together with the 1670 measurement results to a collector. 1672 ma-action-suppression-tags: An optional unordered set of 1673 suppression tags that are used to 1674 select actions to be suppressed. 1676 3.8. Common Objects: Channels 1678 A Channel defines a bi-directional communication channel between the 1679 MA and a Controller or Collector. Multiple Channels can be defined 1680 to enable results to be split or duplicated across different 1681 Collectors. 1683 Each Channel contains the details of the remote endpoint (including 1684 location and security credential information such as the 1685 certificate). The timing of when to communicate over a Channel is 1686 specified by the Schedule which executes the corresponding Control or 1687 Reporting Task. The certificate can be the digital certificate 1688 associated to the FQDN in the URL or it can be the certificate of the 1689 Certification Authority that was used to issue the certificate for 1690 the FQDN (Fully Qualified Domain Name) of the target URL (which will 1691 be retrieved later on using a communication protocol such as TLS). 1692 In order to establish a secure channel, the MA will use its own 1693 security credentials (in the Configuration Information) and the given 1694 credentials for the individual Channel end-point. 1696 As with the Task Configurations, each Channel is also given a text 1697 name by which it can be referenced as a Task Option. 1699 Although the same in terms of information, Channels used for 1700 communication with the Controller are referred to as Control Channels 1701 whereas Channels to Collectors are referred to as Report Channels. 1702 Hence Control Channels will be referenced from Control Tasks executed 1703 by a Control Schedule, whereas Report Channels will be referenced 1704 from within Reporting Tasks executed by an Instruction Schedule. 1706 Multiple interfaces are also supported. For example the Reporting 1707 Task could be configured to send some results over GPRS. This is 1708 especially useful when such results indicate the loss of connectivity 1709 on a different network interface. 1711 Example: A Channel used for reporting results may specify that 1712 results are to be sent to the URL (https://collector.example.org/ 1713 report/), using the appropriate digital certificate to establish a 1714 secure channel. 1716 3.8.1. Definition of ma-channel-obj 1718 object { 1719 string ma-channel-name; 1720 url ma-channel-target; 1721 credentials ma-channel-credentials; 1722 [string ma-channel-interface-name;] 1723 } ma-channel-obj; 1725 The ma-channel-obj consists of the following elements: 1727 ma-channel-name: A unique name identifying the channel 1728 object. 1730 ma-channel-target: A URL identifying the target channel 1731 endpoint. 1733 ma-channel-credentials: The security credentials needed to 1734 establish a secure channel. 1736 ma-channel-interface-name: An optional name of the network interface 1737 to be used. If not present, the IP 1738 protocol stack will select a suitable 1739 interface. 1741 3.9. Common Objects: Task Configurations 1743 Conceptually each Task Configuration defines the parameters of a Task 1744 that the Measurement Agent (MA) may perform at some point in time. 1745 It does not by itself actually instruct the MA to perform them at any 1746 particular time (this is done by a Schedule). Tasks can be 1747 Measurement Tasks (i.e., those Tasks actually performing some type of 1748 passive or active measurement) or any other scheduled activity 1749 performed by the MA such as transferring information to or from the 1750 Controller and Collectors. Other examples of Tasks may include data 1751 manipulation or processing Tasks conducted on the MA. 1753 A Measurement Task Configuration is the same in information terms to 1754 any other Task Configuration. Both measurement and non-measurement 1755 Tasks may have registry entries to enable the MA to uniquely identify 1756 the Task it should execute and retrieve the schema for any parameters 1757 that may be passed to the Task. Registry entries are specified as a 1758 URI and can therefore be used to identify the Task within a namespace 1759 or point to a web or local file location for the Task information. 1760 As mentioned previously, these URIs may be used to identify the 1761 Measurement Task in a public namespace 1762 [I-D.ietf-ippm-metric-registry]. 1764 Example: A Measurement Task Configuration may configure a single 1765 Measurement Task for measuring UDP latency. The Measurement Task 1766 Configuration could define the destination port and address for 1767 the measurement as well as the duration, internal packet timing 1768 strategy and other parameters (for example a stream for one hour 1769 and sending one packet every 500 ms). It may also define the 1770 output type and possible parameters (for example the output type 1771 can be the 95th percentile mean) where the measurement task 1772 accepts such parameters. It does not define when the task starts 1773 (this is defined by the Schedule element), so it does not by 1774 itself instruct the MA to actually perform this Measurement Task. 1776 The Task Configuration will include a local short name for reference 1777 by a Schedule. Task Configurations may also refer to registry 1778 entries as described above. In addition the Task can be configured 1779 through a set of configuration Options. The nature and number of 1780 these Options will depend upon the Task. These options are expressed 1781 as name-value pairs although the 'value' may be a structured object 1782 instead of a simple string or numeric value. The implementation of 1783 these name-value pairs will vary between data models. 1785 An Option that must be present for Reporting Tasks is the Channel 1786 reference specifying how to communicate with a Collector. This is 1787 included in the task options and will have a value that matches a 1788 channel name that has been defined in the Instruction. Similarly 1789 Control Tasks will have a similar option with the value set to a 1790 specified Control Channel. 1792 A Reporting Task might also have a flag parameter, defined as an 1793 Option, to indicate whether to send a report without measurement 1794 results if there is no measurement result data pending to be 1795 transferred to the Collector. In addition many tasks will also take 1796 as a parameter which interface to operate over. 1798 In addition the Task Configuration may optionally also be given tags 1799 that can carry a Measurement Cycle ID. The purpose of this ID is to 1800 easily identify a set of measurement results that have been produced 1801 by Measurement Tasks with comparable Options. This ID could be 1802 manually incremented or otherwise changed when an Option change is 1803 implemented which could mean that two sets of results should not be 1804 directly compared. 1806 3.9.1. Definition of ma-task-obj 1808 object { 1809 string ma-task-name; 1810 ma-registry-obj ma-task-functions<0..*>; 1811 [ma-option-obj ma-task-options<0..*>;] 1812 [string ma-task-tags<0..*>;] 1813 } ma-task-obj; 1815 The ma-task-obj defines a configured task that can be invoked as part 1816 of an action. A configured task can be referenced by its name and it 1817 contains a possibly empty set of URIs to link to registry entries. 1818 Options allow the configuration of task parameters (in the form of 1819 name-value pairs). The ma-task-obj consists of the following 1820 elements: 1822 ma-task-name: A name uniquely identifying a configured 1823 task object. 1825 ma-task-functions: A possibly empty unordered set of registry 1826 entries identifying the functions of the 1827 configured task. 1829 ma-task-options: An optional and possibly empty ordered list 1830 of options (name-value pairs) that are 1831 passed to the configured task. 1833 ma-task-tags: An optional unordered set of tags that are 1834 reported together with the measurement 1835 results to a collector. 1837 3.9.2. Definition of ma-option-obj 1839 object { 1840 string ma-option-name; 1841 [object ma-option-value;] 1842 } ma-option-obj; 1844 The ma-option-obj models a name-value pair and consists of the 1845 following elements: 1847 ma-option-name: The name of the option. 1849 ma-option-value: The optional value of the option. 1851 The ma-option-obj is used to define Task Configuration Options. Task 1852 Configuration Options are generally task specific. For tasks 1853 associated with an entry in a registry, the registry may define well- 1854 known option names (e.g., the so-called parameters in the IPPM metric 1855 registry [I-D.ietf-ippm-metric-registry]). Control and Reporting 1856 Tasks need to know the Channel they are going to use. The common 1857 option name for specifying the channel is "channel" where the 1858 option's value refers to the name of an ma-channel-obj. 1860 3.10. Common Objects: Registry Information 1862 Tasks and actions can be associated with entries in a registry. A 1863 registry object refers to an entry in a registry (identified by a 1864 URI) and it may define a set of roles. 1866 3.10.1. Definition of ma-registry-obj 1868 object { 1869 uri ma-registry-uri; 1870 [string ma-registry-role<0..*>;] 1871 } ma-registry-obj; 1873 The ma-registry-obj refers to an entry of a registry and it defines 1874 the associated role(s). The ma-registry-obj consists of the 1875 following elements: 1877 ma-registry-uri: A URI identifying an entry in a registry. 1879 ma-registry-role: An optional and possibly empty unordered 1880 set of roles for the identified registry 1881 entry. 1883 3.11. Common Objects: Event Information 1885 The Event information object used throughout the information models 1886 can initially take one of several different forms. Additional forms 1887 may be defined later in order to bind the execution of schedules to 1888 additional events. The initially defined Event forms are: 1890 1. Periodic Timing: Emits multiple events periodically according to 1891 an interval time defined in seconds 1893 2. Calendar Timing: Emits multiple events according to a calendar 1894 based pattern, e.g., 22 minutes past each hour of the day on 1895 weekdays 1897 3. One Off Timing: Emits one event at a specific date and time 1899 4. Immediate: Emits one event as soon as possible 1901 5. Startup: Emits an event whenever the MA is started (e.g., at 1902 device startup) 1904 6. Controller Lost: Emits an event when connectivity to the 1905 controller has been lost 1907 7. Controller Connected: Emits an event when connectivity to the 1908 controller has been (re-)established 1910 Optionally each of the Event options may also specify a randomness 1911 that should be evaluated and applied separately to each indicated 1912 event. This randomness parameter defines a uniform interval in 1913 seconds over which the start of the task is delayed from the starting 1914 times specified by the event object. 1916 Both the Periodic and Calendar timing objects allow for a series of 1917 Actions to be executed. While both have an optional end time, it is 1918 best practice to always configure an end time and refresh the 1919 information periodically to ensure that lost MAs do not continue 1920 their tasks forever. 1922 Startup events are only created on device startup, not when a new 1923 Instruction is transferred to the MA. If scheduled task execution is 1924 desired both on the transfer of the Instruction and on device restart 1925 then both the Immediate and Startup timing needs to be used in 1926 conjunction. 1928 The datetime format used for all elements in the information model 1929 MUST conform to RFC 3339 [RFC3339]. 1931 3.11.1. Definition of ma-event-obj 1932 object { 1933 string ma-event-name; 1934 union { 1935 ma-periodic-obj ma-event-periodic; 1936 ma-calendar-obj ma-event-calendar; 1937 ma-one-off-obj ma-event-one-off; 1938 ma-immediate-obj ma-event-immediate; 1939 ma-startup-obj ma-event-startup; 1940 ma-controller-lost-obj ma-event-controller-lost; 1941 ma-controller-connected-obj ma-event-controller-connected; 1942 } 1943 [int ma-event-random-spread;] 1944 [int ma-event-cycle-interval;] 1945 } ma-event-obj; 1947 The ma-event-obj is the main event object. Event objects are 1948 identified by a name. A generic event object itself contains a more 1949 specific event object. The set of specific event objects should be 1950 extensible. The initial set of specific event objects is further 1951 described below. The ma-event-obj also includes an optional uniform 1952 random spread that can be used to randomize the start times of 1953 schedules triggered by an event. The ma-event-obj consists of the 1954 following elements: 1956 ma-event-name: The name uniquely identifies an event 1957 object. Schedules refer to event 1958 objects by this name. 1960 ma-event-periodic: The ma-event-periodic is present for 1961 periodic timing objects. 1963 ma-event-calendar: The ma-event-calendar is present for 1964 calendar timing objects. 1966 ma-event-one-off: The ma-event-one-off is present for 1967 one-off timing objects. 1969 ma-event-immediate: The ma-event-immediate is present for 1970 immediate event objects. 1972 ma-event-startup: The ma-event-startup is present for 1973 startup event objects. 1975 ma-event-controller-lost: The ma-event-controller-lost is 1976 present for connectivity to 1977 controller lost event objects. 1979 ma-event-controller-connected: The ma-event-controller-connected is 1980 present for connectivity to a 1981 controller established event objects. 1983 ma-event-random-spread: The optional ma-event-random-spread 1984 adds a random delay defined in 1985 seconds to the event object. No 1986 random delay is added if ma-event- 1987 random-spread does not exist. 1989 ma-event-cycle-interval: The optional ma-event-cycle-interval 1990 defines the duration of the time 1991 interval in seconds that is used to 1992 calculate cycle numbers. No cycle 1993 number is calculated if ma-event- 1994 cycle-interval does not exist. 1996 3.11.2. Definition of ma-periodic-obj 1998 object { 1999 [datetime ma-periodic-start;] 2000 [datetime ma-periodic-end;] 2001 int ma-periodic-interval; 2002 } ma-periodic-obj; 2004 The ma-periodic-obj timing object has an optional start and an 2005 optional end time plus a periodic interval. Schedules using an ma- 2006 periodic-obj are started periodically between the start and end time. 2007 The ma-periodic-obj consists of the following elements: 2009 ma-periodic-start: The optional date and time at which 2010 Schedules using this object are first 2011 started. If not present it defaults to 2012 immediate. 2014 ma-periodic-end: The optional date and time at which 2015 Schedules using this object are last 2016 started. If not present it defaults to 2017 indefinite. 2019 ma-periodic-interval: The interval defines the time in seconds 2020 between two consecutive starts of tasks. 2022 3.11.3. Definition of ma-calendar-obj 2024 Calendar Timing supports the routine execution of Schedules at 2025 specific times and/or on specific dates. It can support more 2026 flexible timing than Periodic Timing since the execution of Schedules 2027 does not have to be uniformly spaced. For example a Calendar Timing 2028 could support the execution of a Measurement Task every hour between 2029 6pm and midnight on weekdays only. 2031 Calendar Timing is also required to perform measurements at 2032 meaningful times in relation to network usage (e.g., at peak times). 2033 If the optional timezone offset is not supplied then local system 2034 time is assumed. This is essential in some use cases to ensure 2035 consistent peak-time measurements as well as supporting MA devices 2036 that may be in an unknown timezone or roam between different 2037 timezones (but know their own timezone information such as through 2038 the mobile network). 2040 The calendar elements within the Calendar Timing do not have defaults 2041 in order to avoid accidental high-frequency execution of Tasks. If 2042 all possible values for an element are desired then the wildcard * is 2043 used. 2045 object { 2046 [datetime ma-calendar-start;] 2047 [datetime ma-calendar-end;] 2048 [string ma-calendar-months<0..*>;] 2049 [string ma-calendar-days-of-week<0..*>;] 2050 [string ma-calendar-days-of-month<0..*>;] 2051 [string ma-calendar-hours<0..*>;] 2052 [string ma-calendar-minutes<0..*>;] 2053 [string ma-calendar-seconds<0..*>;] 2054 [int ma-calendar-timezone-offset;] 2055 } ma-calendar-obj; 2057 ma-calendar-start: The optional date and time at which 2058 Schedules using this object are first 2059 started. If not present it defaults to 2060 immediate. 2062 ma-calendar-end: The optional date and time at which 2063 Schedules using this object are last 2064 started. If not present it defaults to 2065 indefinite. 2067 ma-calendar-months: The optional set of months (1-12) on 2068 which tasks scheduled using this object 2069 are started. The wildcard * means all 2070 months. If not present, it defaults to 2071 no months. 2073 ma-calendar-days-of-week: The optional set of days of a week 2074 ("Mon", "Tue", "Wed", "Thu", "Fri", 2075 "Sat", "Sun") on which tasks scheduled 2076 using this object are started. The 2077 wildcard * means all days of the week. 2078 If not present, it defaults to no days. 2080 ma-calendar-days-of-month: The optional set of days of a months 2081 (1-31) on which tasks scheduled using 2082 this object are started. The wildcard 2083 * means all days of a months. If not 2084 present, it defaults to no days. 2086 ma-calendar-hours: The optional set of hours (0-23) on 2087 which tasks scheduled using this object 2088 are started. The wildcard * means all 2089 hours of a day. If not present, it 2090 defaults to no hours. 2092 ma-calendar-minutes: The optional set of minutes (0-59) on 2093 which tasks scheduled using this object 2094 are started. The wildcard * means all 2095 minutes of an hour. If not present, it 2096 defaults to no hours. 2098 ma-calendar-seconds: The optional set of seconds (0-59) on 2099 which tasks scheduled using this object 2100 are started. The wildcard * means all 2101 seconds of an hour. If not present, it 2102 defaults to no seconds. 2104 ma-calendar-timezone-offset: The optional timezone offest in hours. 2105 If not present, it defaults to the 2106 system's local timezone. 2108 If a day of the month is specified that does not exist in the month 2109 (e.g., 29th of Feburary) then those values are ignored. 2111 3.11.4. Definition of ma-one-off-obj 2113 object { 2114 datetime ma-one-off-time; 2115 } ma-one-off-obj; 2117 The ma-one-off-obj timing object specifies a fixed point in time. 2118 Schedules using an ma-one-off-obj are started once at the specified 2119 date and time. The ma-one-off-obj consists of the following 2120 elements: 2122 ma-one-off-time: The date and time at which Schedules using 2123 this object are started. 2125 3.11.5. Definition of ma-immediate-obj 2127 object { 2128 // empty 2129 } ma-immediate-obj; 2131 The ma-immediate-obj event object has no further information 2132 elements. Schedules using an ma-immediate-obj are started as soon as 2133 possible. 2135 3.11.6. Definition of ma-startup-obj 2137 object { 2138 // empty 2139 } ma-startup-obj; 2141 The ma-startup-obj event object has no further information elements. 2142 Schedules or suppressions using an ma-startup-obj are started at MA 2143 initialization time. 2145 3.11.7. Definition of ma-controller-lost-obj 2147 object { 2148 // empty 2149 } ma-controller-lost-obj; 2151 The ma-controller-lost-obj event object has no further information 2152 elements. The ma-controller-lost-obj indicates that connectivity to 2153 the controller has been lost. This is determined by a timer started 2154 after each successful contact with a controller. When the timer 2155 reaches the controller-timeout (measured in seconds), an ma- 2156 controller-lost-obj event is generated. This event may be used to 2157 start a suppression. 2159 3.11.8. Definition of ma-controller-connected-obj 2161 object { 2162 // empty 2163 } ma-controller-connected-obj; 2165 The ma-controller-connected-obj event object has no further 2166 information elements. The ma-controller-connected-obj indicates that 2167 connectivity to the controller has been established again after it 2168 was lost. This event may be used to end a suppression. 2170 4. Example Execution 2172 The example execution has two event sources E1 and E2 and three 2173 schedules S1, S2, and S3. The schedule S3 is started by events of 2174 event source E2 while the schedules S1 and S2 are both started by 2175 events of the event source E1. The schedules S1 and S2 have two 2176 actions each and schedule S3 has a single action. The event source 2177 E2 has no randomization while the event source E1 has the 2178 randomization r. 2180 Figure 2 shows a possible timeline of an execution. The time T is 2181 progressing downwards. The dotted vertial line indicates progress of 2182 time while a dotted horizontal line indicates which schedule are 2183 triggered by an event. Tilded lines indicate data flowing from an 2184 action to another schedule. Actions within a schedule are named A1, 2185 A2, etc. 2187 E2 E1 T S1 S2 S3 2188 sequential parallel pipelined 2189 : 2190 e0 + 2191 : 2192 : 2193 e0+r + .......... + .......... ++ 2194 : | A1 A1 || A2 2195 : + |+ ~~~~~~~> 2196 : | A2 | 2197 : | + ~~~~~~~~> 2198 : + ~~~~~~~~~~~~~~~~~~~~~> 2199 : 2200 : 2201 e1 + 2202 : 2203 e1+r + .......... + .......... ++ 2204 : | A1 A1 || 2205 : | +|~~~~~~~> 2206 : | | A2 2207 : + +~~~~~~~> 2208 : | A2 2209 : + ~~~~~~~~~~~~~~~~~~~~> 2210 e0 + ................................... + 2211 : | A1 2212 e3 + | 2213 e3+r + .......... + .......... ++ | 2214 : | A1 A1 || A2 | 2215 : + ++ ~~~~~~> | 2216 : | A2 + 2217 : + ~~~~~~~~~~~~~~~~~~~~> 2218 V 2220 Figure 2: Example Execution 2222 Note that implementations must handle possible concurrency issues. 2223 In the example execution, action A1 of schedule S3 is consuming the 2224 data that has been forwarded to schedule S3 while additional data is 2225 arriving from action A2 of schedule S2. 2227 5. IANA Considerations 2229 This document makes no request of IANA. 2231 Note to the RFC Editor: this section may be removed on publication as 2232 an RFC. 2234 6. Security Considerations 2236 This Information Model deals with information about the control and 2237 reporting of the Measurement Agent. There are broadly two security 2238 considerations for such an Information Model. Firstly the 2239 Information Model has to be sufficient to establish secure 2240 communication channels to the Controller and Collector such that 2241 other information can be sent and received securely. Additionally, 2242 any mechanisms that the Network Operator or other device 2243 administrator employs to pre-configure the MA must also be secure to 2244 protect unauthorized parties from modifying pre-configuration 2245 information. These mechanisms are important to ensure that the MA 2246 cannot be hijacked, for example to participate in a distributed 2247 denial of service attack. 2249 The second consideration is that no mandated information items should 2250 pose a risk to confidentiality or privacy given such secure 2251 communication channels. For this latter reason items such as the MA 2252 context and MA ID are left optional and can be excluded from some 2253 deployments. This may, for example, allow the MA to remain anonymous 2254 and for information about location or other context that might be 2255 used to identify or track the MA to be omitted or blurred. 2256 Implementations and deployments should also be careful about exposing 2257 device-ids when this is not strictly needed. 2259 An implementation of this Information Model should support wherever 2260 relevant, all the security and privacy requirements associated with 2261 the LMAP Framework. In addition, users of this Information Model are 2262 advised to choose identifiers for Group IDs, tags or names of 2263 information model objects (e.g., configured tasks, schedules or 2264 actions) that do not reveal any sensitive information to people 2265 authorized to process measurement results but who are not authorized 2266 to know details about the Measurement Agents that were used to 2267 perform the measurement. 2269 7. Acknowledgements 2271 Several people contributed to this specification by reviewing early 2272 versions and actively participating in the LMAP working group 2273 (apologies to those unintentionally omitted): Vaibhav Bajpai, Michael 2274 Bugenhagen, Timothy Carey, Alissa Cooper, Kenneth Ko, Al Morton, Dan 2275 Romascanu, Henning Schulzrinne, Andrea Soppera, Barbara Stark, and 2276 Jason Weil. 2278 Trevor Burbridge, Philip Eardley, Marcelo Bagnulo and Juergen 2279 Schoenwaelder worked in part on the Leone research project, which 2280 received funding from the European Union Seventh Framework Programme 2281 [FP7/2007-2013] under grant agreement number 317647. 2283 Juergen Schoenwaelder was partly funded by Flamingo, a Network of 2284 Excellence project (ICT-318488) supported by the European Commission 2285 under its Seventh Framework Programme. 2287 8. References 2289 8.1. Normative References 2291 [ISO.10646] 2292 International Organization for Standardization, 2293 "Information Technology - Universal Multiple-Octet Coded 2294 Character Set (UCS)", ISO Standard 10646:2014, 2014. 2296 [POSIX.2] The IEEE and The Open Group, "The Open Group Base 2297 Specifications Issue 7", IEEE Standard 1003.1-2008, 2016. 2299 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2300 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 2301 RFC2119, March 1997, 2302 . 2304 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 2305 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 2306 . 2308 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2309 Resource Identifier (URI): Generic Syntax", STD 66, RFC 2310 3986, DOI 10.17487/RFC3986, January 2005, 2311 . 2313 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 2314 Unique IDentifier (UUID) URN Namespace", RFC 4122, DOI 10 2315 .17487/RFC4122, July 2005, 2316 . 2318 8.2. Informative References 2320 [I-D.ietf-ippm-metric-registry] 2321 Bagnulo, M., Claise, B., Eardley, P., Morton, A., and A. 2322 Akhter, "Registry for Performance Metrics", draft-ietf- 2323 ippm-metric-registry-10 (work in progress), November 2016. 2325 [I-D.ietf-lmap-yang] 2326 Schoenwaelder, J. and V. Bajpai, "A YANG Data Model for 2327 LMAP Measurement Agents", draft-ietf-lmap-yang-10 (work in 2328 progress), January 2017. 2330 [RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between 2331 Information Models and Data Models", RFC 3444, DOI 10 2332 .17487/RFC3444, January 2003, 2333 . 2335 [RFC7398] Bagnulo, M., Burbridge, T., Crawford, S., Eardley, P., and 2336 A. Morton, "A Reference Path and Measurement Points for 2337 Large-Scale Measurement of Broadband Performance", RFC 2338 7398, DOI 10.17487/RFC7398, February 2015, 2339 . 2341 [RFC7594] Eardley, P., Morton, A., Bagnulo, M., Burbridge, T., 2342 Aitken, P., and A. Akhter, "A Framework for Large-Scale 2343 Measurement of Broadband Performance (LMAP)", RFC 7594, 2344 DOI 10.17487/RFC7594, September 2015, 2345 . 2347 Appendix A. Change History 2349 Note to the RFC Editor: this section should be removed on publication 2350 as an RFC. 2352 A.1. Non-editorial changes since -16 2354 o Addressing Alissa Cooper's review comments. 2356 A.2. Non-editorial changes since -15 2358 o The reference to the framework is now informational. 2360 A.3. Non-editorial changes since -14 2362 o Clarified that the cycle number is in UTC. 2364 A.4. Non-editorial changes since -13 2366 o Removed the ma-config-device-id from the ma-config-obj. 2368 o Added ma-config-report-group-id and clarified how two flags ma- 2369 config-report-agent-id and ma-config-report-group-id work. 2371 A.5. Non-editorial changes since -12 2373 o Renamed the ma-metrics-registry-obj to ma-registry-obj since tasks 2374 may refer to different registries (not just a metrics registry). 2376 o Clarifications and bug fixes. 2378 A.6. Non-editorial changes since -11 2380 o Clarifications and bug fixes. 2382 A.7. Non-editorial changes since -10 2384 o Rewrote the text concerning the well-known "channel" option name. 2386 o Added ma-report-result-event-time, ma-report-result-cycle-number, 2387 and ma-event-cycle-interval. 2389 o Added ma-capability-tags. 2391 o Added a new section showing an example execution. 2393 o Several clarifications and bug fixes. 2395 A.8. Non-editorial changes since -09 2397 o Added ma-status-schedule-storage and ma-status-action-storage. 2399 o Removed suppress-by-default. 2401 o Moved ma-report-result-metrics of the ma-report-result-obj to ma- 2402 report-table-metrics of the ma-report-table-obj so that the 2403 relationship between metrics and result tables is clear. 2405 o Added ma-report-conflict-obj. 2407 o Added ma-report-result-status to ma-report-result-obj. 2409 o Several clarifications and bug fixes. 2411 A.9. Non-editorial changes since -08 2413 o Refactored the ma-report-task-obj into the ma-report-result-obj. 2415 o Introduced the ma-report-table-obj so that a result can contain 2416 multiple tables. 2418 o Report schedule, action, and task name as part of the ma-report- 2419 result-obj. 2421 o Report conflicts per ma-report-result-obj and not per ma-report- 2422 row-obj. 2424 o Report the start/end time as part of the ma-report-result-obj. 2426 A.10. Non-editorial changes since -07 2428 o Added ma-schedule-end and ma-schedule-duration. 2430 o Changed the granularity of scheduler timings to seconds. 2432 o Added ma-status-suppression-obj to report the status of 2433 suppressions as done in the YANG data model. 2435 o Added counters to schedule and action status objects to match the 2436 counters in the YANG data model. 2438 o Using tags to pass information such as a measurement cycle 2439 identifier to the collector. 2441 o Using suppression tags and glob-style matching to select schedules 2442 and actions to be suppressed. 2444 A.11. Non-editorial changes since -06 2446 o The default execution mode is pipelined (LI12) 2448 o Added text to define which action consumes data in sequential, 2449 pipelines, and parallel execution mode (LI11) 2451 o Added ma-config-measurement-point, ma-report-measurement-point, 2452 and ma-config-report-measurement-point to configure and report the 2453 measurement point (LI10) 2455 o Turned ma-suppression-obj into a list that uses a start event and 2456 a stop event to define the start and end of suppression; this 2457 unifies the handling of suppression and loss of controller 2458 connectivity (LI09) 2460 o Added ma-controller-lost-obj and ma-controller-ok-obj event 2461 objects (LI09) 2463 o Added ma-status-schedule-obj to report the status of a schedule 2464 and refactored ma-task-status-obj into ma-status-action-obj to 2465 report the status of an action (LI07, LI08) 2467 o Introduced a common ma-metric-registry-obj that identifies a 2468 metric and a set of associated roles and added this object to 2469 expose metric capabilities and to support the configuration of 2470 metrics and to report the metrics used (LI06) 2472 o Introduced ma-capability-obj and ma-capability-task-obj to expose 2473 the capabilities of a measurement agent (LI05) 2475 o Use 'ordered list' or 'unordered set' instead of list, collection, 2476 etc. (LI02) 2478 o Clarification that Actions are part of a Schedule (LI03) 2480 o Deleted terms that are not strictly needed (LI04) 2482 A.12. Non-editorial changes since -05 2484 o A task can now reference multiply registry entries. 2486 o Consistent usage of the term Action and Task. 2488 o Schedules are triggered by Events instead of Timings; Timings are 2489 just one of many possible event sources. 2491 o Actions feed into other Schedules (instead of Actions within other 2492 Schedules). 2494 o Removed the notion of multiple task outputs. 2496 o Support for sequential, parallel, and pipelined execution of 2497 Actions. 2499 Authors' Addresses 2501 Trevor Burbridge 2502 BT 2503 Adastral Park, Martlesham Heath 2504 Ipswich IP5 3RE 2505 United Kingdom 2507 Email: trevor.burbridge@bt.com 2509 Philip Eardley 2510 BT 2511 Adastral Park, Martlesham Heath 2512 Ipswich IP5 3RE 2513 United Kingdom 2515 Email: philip.eardley@bt.com 2516 Marcelo Bagnulo 2517 Universidad Carlos III de Madrid 2518 Av. Universidad 30 2519 Leganes, Madrid 28911 2520 Spain 2522 Email: marcelo@it.uc3m.es 2524 Juergen Schoenwaelder 2525 Jacobs University Bremen 2526 Campus Ring 1 2527 Bremen 28759 2528 Germany 2530 Email: j.schoenwaelder@jacobs-university.de