idnits 2.17.00 (12 Aug 2021) /tmp/idnits16881/draft-ietf-lmap-information-model-11.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 695 has weird spacing: '...ion-obj ma-in...' == Line 883 has weird spacing: '...ask-obj ma-ca...' == Line 908 has weird spacing: '...try-obj ma-ca...' == Line 929 has weird spacing: '...ace-obj ma-...' == Line 931 has weird spacing: '...ion-obj ma-st...' == (8 more instances...) -- The document date (August 19, 2016) is 2100 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) ** Downref: Normative reference to an Informational RFC: RFC 7594 == 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: 1 error (**), 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: February 20, 2017 M. Bagnulo 6 Universidad Carlos III de Madrid 7 J. Schoenwaelder 8 Jacobs University Bremen 9 August 19, 2016 11 Information Model for Large-Scale Measurement Platforms (LMAP) 12 draft-ietf-lmap-information-model-11 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 February 20, 2017. 48 Copyright Notice 50 Copyright (c) 2016 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 4 67 3. LMAP Information Model . . . . . . . . . . . . . . . . . . . 5 68 3.1. Pre-Configuration Information . . . . . . . . . . . . . . 8 69 3.1.1. Definition of ma-preconfig-obj . . . . . . . . . . . 9 70 3.2. Configuration Information . . . . . . . . . . . . . . . . 10 71 3.2.1. Definition of ma-config-obj . . . . . . . . . . . . . 11 72 3.3. Instruction Information . . . . . . . . . . . . . . . . . 13 73 3.3.1. Definition of ma-instruction-obj . . . . . . . . . . 15 74 3.3.2. Definition of ma-suppression-obj . . . . . . . . . . 16 75 3.4. Logging Information . . . . . . . . . . . . . . . . . . . 17 76 3.4.1. Definition of ma-log-obj . . . . . . . . . . . . . . 18 77 3.5. Capability and Status Information . . . . . . . . . . . . 19 78 3.5.1. Definition of ma-capability-obj . . . . . . . . . . . 19 79 3.5.2. Definition of ma-capability-task-obj . . . . . . . . 20 80 3.5.3. Definition of ma-status-obj . . . . . . . . . . . . . 20 81 3.5.4. Definition of ma-status-schedule-obj . . . . . . . . 21 82 3.5.5. Definition of ma-status-action-obj . . . . . . . . . 22 83 3.5.6. Definition of ma-status-suppression-obj . . . . . . . 24 84 3.5.7. Definition of ma-status-interface-obj . . . . . . . . 25 85 3.6. Reporting Information . . . . . . . . . . . . . . . . . . 25 86 3.6.1. Definition of ma-report-obj . . . . . . . . . . . . . 27 87 3.6.2. Definition of ma-report-result-obj . . . . . . . . . 28 88 3.6.3. Definition of ma-report-conflict-obj . . . . . . . . 30 89 3.6.4. Definition of ma-report-table-obj . . . . . . . . . . 30 90 3.6.5. Definition of ma-report-row-obj . . . . . . . . . . . 31 91 3.7. Common Objects: Schedules . . . . . . . . . . . . . . . . 31 92 3.7.1. Definition of ma-schedule-obj . . . . . . . . . . . . 33 93 3.7.2. Definition of ma-action-obj . . . . . . . . . . . . . 34 94 3.8. Common Objects: Channels . . . . . . . . . . . . . . . . 35 95 3.8.1. Definition of ma-channel-obj . . . . . . . . . . . . 35 97 3.9. Common Objects: Task Configurations . . . . . . . . . . . 36 98 3.9.1. Definition of ma-task-obj . . . . . . . . . . . . . . 37 99 3.9.2. Definition of ma-option-obj . . . . . . . . . . . . . 38 100 3.10. Common Objects: Registry Information . . . . . . . . . . 38 101 3.10.1. Definition of ma-metric-registry-obj . . . . . . . . 39 102 3.11. Common Objects: Event Information . . . . . . . . . . . . 39 103 3.11.1. Definition of ma-event-obj . . . . . . . . . . . . . 40 104 3.11.2. Definition of ma-periodic-obj . . . . . . . . . . . 41 105 3.11.3. Definition of ma-calendar-obj . . . . . . . . . . . 42 106 3.11.4. Definition of ma-one-off-obj . . . . . . . . . . . . 44 107 3.11.5. Definition of ma-immediate-obj . . . . . . . . . . . 44 108 3.11.6. Definition of ma-startup-obj . . . . . . . . . . . . 44 109 3.11.7. Definition of ma-controller-lost-obj . . . . . . . . 44 110 3.11.8. Definition of ma-controller-connected-obj . . . . . 45 111 4. Example Execution . . . . . . . . . . . . . . . . . . . . . . 45 112 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 46 113 6. Security Considerations . . . . . . . . . . . . . . . . . . . 47 114 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 47 115 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 47 116 8.1. Normative References . . . . . . . . . . . . . . . . . . 47 117 8.2. Informative References . . . . . . . . . . . . . . . . . 48 118 Appendix A. Non-editorial Changes since -10 . . . . . . . . . . 48 119 Appendix B. Non-editorial Changes since -09 . . . . . . . . . . 49 120 Appendix C. Non-editorial Changes since -08 . . . . . . . . . . 49 121 Appendix D. Non-editorial Changes since -07 . . . . . . . . . . 49 122 Appendix E. Non-editorial Changes since -06 . . . . . . . . . . 50 123 Appendix F. Non-editorial Changes since -05 . . . . . . . . . . 50 124 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 51 126 1. Introduction 128 A large-scale measurement platform is a collection of components that 129 work in a coordinated fashion to perform measurements from a large 130 number of vantage points. The main components of a large-scale 131 measurement platform are the Measurement Agents (hereafter MAs), the 132 Controller(s) and the Collector(s). 134 The MAs are the elements actually performing the measurements. The 135 MAs are controlled by exactly one Controller at a time and the 136 Collectors gather the results generated by the MAs. In a nutshell, 137 the normal operation of a large-scale measurement platform starts 138 with the Controller instructing a set of one or more MAs to perform a 139 set of one or more Measurement Tasks at a certain point in time. The 140 MAs execute the instructions from a Controller, and once they have 141 done so, they report the results of the measurements to one or more 142 Collectors. The overall framework for a Large Measurement platform 143 as used in this document is described in detail in [RFC7594]. 145 A large-scale measurement platform involves basically three types of 146 protocols, namely, a Control protocol (or protocols) between a 147 Controller and the MAs, a Report protocol (or protocols) between the 148 MAs and the Collector(s) and several measurement protocols between 149 the MAs and Measurement Peers (MPs), used to actually perform the 150 measurements. In addition some information is required to be 151 configured on the MA prior to any communication with a Controller. 153 This document defines the information model for both Control and the 154 Report protocols along with pre-configuration information that is 155 required on the MA before communicating with the Controller, broadly 156 named as the LMAP Information Model. The measurement protocols are 157 out of the scope of this document. 159 As defined in [RFC3444], the LMAP Information Model defines the 160 concepts involved in a large-scale measurement platform at a high 161 level of abstraction, independent of any specific implementation or 162 actual protocol used to exchange the information. It is expected 163 that the proposed information model can be used with different 164 protocols in different measurement platform architectures and across 165 different types of MA devices (e.g., home gateway, smartphone, PC, 166 router). A YANG data model implementing the information model can be 167 found in [I-D.ietf-lmap-yang]. 169 The definition of an Information Model serves a number of purposes: 171 1. To guide the standardisation of one or more Control and Report 172 protocols and data models 174 2. To enable high-level inter-operability between different Control 175 and Report protocols by facilitating translation between their 176 respective data models such that a Controller could instruct sub- 177 populations of MAs using different protocols 179 3. To form agreement of what information needs to be held by an MA 180 and passed over the Control and Report interfaces and support the 181 functionality described in the LMAP framework 183 4. To enable existing protocols and data models to be assessed for 184 their suitability as part of a large-scale measurement system 186 2. Notation 188 This document uses a programming language-like notation to define the 189 properties of the objects of the information model. An optional 190 property is enclosed by square brackets, [ ], and a list property is 191 indicated by two numbers in angle brackets, , where m indicates 192 the minimal number of values, and n is the maximum. The symbol * for 193 n means no upper bound. 195 3. LMAP Information Model 197 The information described herein relates to the information stored, 198 received or transmitted by a Measurement Agent as described within 199 the LMAP framework [RFC7594]. As such, some subsets of this 200 information model are applicable to the measurement Controller, 201 Collector and any device management system that pre-configures the 202 Measurement Agent. The information described in these models will be 203 transmitted by protocols using interfaces between the Measurement 204 Agent and such systems according to a Data Model. 206 For clarity the information model is divided into six sections: 208 1. Pre-Configuration Information. Information pre-configured on the 209 Measurement Agent prior to any communication with other 210 components of the LMAP architecture (i.e., the Controller, 211 Collector and Measurement Peers), specifically detailing how to 212 communicate with a Controller and whether the device is enabled 213 to participate as an MA. 215 2. Configuration Information. Update of the pre-configuration 216 information during the registration of the MA or subsequent 217 communication with the Controller, along with the configuration 218 of further parameters about the MA (rather than the Measurement 219 Tasks it should perform) that were not mandatory for the initial 220 communication between the MA and a Controller. 222 3. Instruction Information. Information that is received by the MA 223 from the Controller pertaining to the Measurement Tasks that 224 should be executed. This includes the task execution Schedules 225 (other than the Controller communication Schedule supplied as 226 (pre)configuration information) and related information such as 227 the Task Configuration, communication Channels to Collectors and 228 schedule Event and Timing information. It also includes Task 229 Suppression information that is used to over-ride normal Task 230 execution. 232 4. Logging Information. Information transmitted from the MA to the 233 Controller detailing the results of any configuration operations 234 along with error and status information from the operation of the 235 MA. 237 5. Capability and Status Information. Information on the general 238 status and capabilities of the MA. For example, the set of 239 measurements that are supported on the device. 241 6. Reporting Information. Information transmitted from the MA to 242 one or more Collectors including measurement results and the 243 context in which they were conducted. 245 In addition the MA may hold further information not described herein, 246 and which may be optionally transferred to or from other systems 247 including the Controller and Collector. One example of information 248 in this category is subscriber or line information that may be 249 extracted by a task and reported by the MA in the reporting 250 communication to a Collector. 252 It should also be noted that the MA may be in communication with 253 other management systems which may be responsible for configuring and 254 retrieving information from the MA device. Such systems, where 255 available, can perform an important role in transferring the pre- 256 configuration information to the MA or enabling/disabling the 257 measurement functionality of the MA. 259 The Information Model is divided into sub-sections for a number of 260 reasons. Firstly the grouping of information facilitates reader 261 understanding. Secondly, the particular groupings chosen are 262 expected to map to different protocols or different transmissions 263 within those protocols. 265 The granularity of data transmitted in each operation of the Control 266 and Report Protocols is not dictated by the Information Model. For 267 example, the Instruction object may be delivered in a single 268 operation. Alternatively, Schedules and Task Configurations may be 269 separated or even each Schedule/Task Configuration may be delivered 270 individually. Similarly the Information Model does not dictate 271 whether data is read, write, or read/write. For example, some 272 Control Protocols may have the ability to read back Configuration and 273 Instruction information which have been previously set on the MA. 274 Lastly, while some protocols may simply overwrite information (for 275 example refreshing the entire Instruction Information), other 276 protocols may have the ability to update or delete selected items of 277 information. 279 The information in these six sections is captured by a number of 280 common information objects. These objects are also described later 281 in this document and comprise of: 283 1. Schedules. A set of Schedules tells the MA to do something. 284 Without a Schedule no Task (from a measurement to reporting or 285 communicating with the Controller) is ever executed. Schedules 286 are used within the Instruction to specify what tasks should be 287 performed, when, and how to direct their results. A Schedule is 288 also used within the pre-Configuration and Configuration 289 information in order to execute the Task or Tasks required to 290 communicate with the Controller. A specific Schedule can only be 291 active once. Attempts to start a Schedule while the same 292 Schedule is still running will fail. 294 2. Channels. A set of Channel objects are used to communicate with 295 a number of endpoints (i.e., the Controller and Collectors). 296 Each Channel object contains the information required for the 297 communication with a single endpoint such as the target location 298 and security details. 300 3. Task Configurations. A set of Task Configurations is used to 301 configure the Tasks that are run by the MA. This includes the 302 registry entries for the Task and any configuration parameters. 303 Task Configurations are referenced from a Schedule in order to 304 specify what Tasks the MA should execute. 306 4. Events. A set of Event objects that can be referenced from the 307 Schedules. Each Schedule always references exactly one Event 308 object that determines when the schedule is executed. An Event 309 object specifies either a singleton or series of events that 310 indicate when Tasks should be executed. A commonly used kind of 311 Event objects are Timing objects. 313 Figure 1 illustrates the structure in which these common information 314 objects are referenced. The references are achieved by each object 315 (Task Configuration, Event) being given a short textual name that is 316 used by other objects. The objects shown in parenthesis are part of 317 the internal object structure of a Schedule. Channels are not shown 318 in the diagram since they are only used as an option by selected Task 319 Configurations but are similarly referenced using a short text name. 321 Schedule 322 |-- triggered by --> Event 323 | 324 |-- executes --> Action 1 325 | |-- using --> Task Configuration 326 | | 327 | `-- feeding to --> Destination Schedule 328 : 329 : 330 `-- executes --> Action N 331 |-- using --> Task Configuration 332 | 333 `-- feeding to --> Destination Schedule 335 Figure 1: Relationship between Schedules, Events, Actions, Task 336 Configurations, and Destination Schedules 338 The primary function of an MA is to execute Schedules. Every Action 339 contained in a Schedule is defined as a Task. As such, these Actions 340 are configured through Task Configurations and executed according to 341 the Event object referenced by the Schedule in which they appear. 342 Note, however, that Actions can have Action specific parameters. 344 Tasks can implement a variety of different types of Actions. While 345 in terms of the Information Model, all Tasks have the same structure, 346 it can help conceptually to think of different Task categories: 348 1. Measurement Tasks measure some aspect of network performance or 349 traffic. They may also capture contextual information from the 350 MA device or network interfaces such as the device type or 351 interface speed. 353 2. Data Transfer Tasks support the communication with a Controller 354 and Collectors: 356 A. Reporting Tasks report the results of Measurement Tasks to 357 Collectors 359 B. Control Task(s) implement the Control Protocol and 360 communicate with the Controller. 362 3. Data Analysis Tasks can exist to analyse data from other 363 Measurement Tasks locally on the MA 365 4. Data Management Tasks may exist to clean-up, filter or compress 366 data on the MA such as Measurement Task results 368 Figure 1 indicates that Actions can produce data that is fed into 369 Destination Schedules. This can by used by Actions implementing 370 Measurement Tasks to feed measurement results to a Schedule that 371 triggers Actions implementing Reporting Tasks. Data fed to a 372 Destination Schedule is consumed by the first Action of the 373 Destination Schedule if the Destination Schedule is using sequential 374 or pipelined execution mode and it is consumed by all Actions of the 375 Destination Schedule if the Destination Schedule is using parallel 376 execution mode. 378 3.1. Pre-Configuration Information 380 This information is the minimal information that needs to be pre- 381 configured to the MA in order for it to successfully communicate with 382 a Controller during the registration process. Some of the Pre- 383 Configuration Information elements are repeated in the Configuration 384 Information in order to allow an LMAP Controller to update these 385 items. The pre-configuration information also contains some elements 386 that are not under the control of the LMAP framework (such as the 387 device identifier and device security credentials). 389 This Pre-Configuration Information needs to include a URL of the 390 initial Controller from where configuration information can be 391 communicated along with the security information required for the 392 communication including the certificate of the Controller (or the 393 certificate of the Certification Authority which was used to issue 394 the certificate for the Controller). All this is expressed as a 395 Channel. While multiple Channels may be provided in the Pre- 396 Configuration Information they must all be associated with a single 397 Controller (e.g., over different interfaces or network protocols). 399 Where the MA pulls information from the Controller, the Pre- 400 Configuration Information also needs to contain the timing of the 401 communication with the Controller as well as the nature of the 402 communication itself (such as the protocol and data to be 403 transferred). The timing is given as a Schedule that executes the 404 Task(s) responsible for communication with the Controller. It is 405 this Task (or Tasks) that implement the Control protocol between the 406 MA and the Controller and utilises the Channel information. The 407 Task(s) may take additional parameters in which case a Task 408 Configuration can also be included. 410 Even where information is pushed to the MA from the Controller 411 (rather than pulled by the MA), a Schedule still needs to be 412 supplied. In this case the Schedule will simply execute a Controller 413 listener task when the MA is started. A Channel is still required 414 for the MA to establish secure communication with the Controller. 416 It can be seen that these Channels, Schedules and Task Configurations 417 for the initial MA-Controller communication are no different in terms 418 of the Information Model to any other Channel, Schedule or Task 419 Configuration that might execute a Measurement Task or report the 420 measurement results (as described later). 422 The MA may be pre-configured with an MA ID, or may use a Device ID in 423 the first Controller contact before it is assigned an MA ID. The 424 Device ID may be a MAC address or some other device identifier 425 expressed as a URI. If the MA ID is not provided at this stage then 426 it must be provided by the Controller during Configuration. 428 3.1.1. Definition of ma-preconfig-obj 429 object { 430 [uuid ma-preconfig-agent-id;] 431 ma-task-obj ma-preconfig-control-tasks<1..*>; 432 ma-channel-obj ma-preconfig-control-channels<1..*>; 433 ma-schedule-obj ma-preconfig-control-schedules<1..*>; 434 [uri ma-preconfig-device-id;] 435 credentials ma-preconfig-credentials; 436 } ma-preconfig-obj; 438 The ma-preconfig-obj is essentially a subset of the ma-config-obj 439 described below. The ma-preconfig-obj consists of the following 440 elements: 442 ma-preconfig-agent-id: An optional uuid uniquely identifying 443 the measurement agent. 445 ma-preconfig-control-tasks: An unordered set of tasks objects. 447 ma-preconfig-control-channels: An unordered set of channel objects. 449 ma-preconfig-control-schedules: An unordered set of scheduling 450 objects. 452 ma-preconfig-device-id: An optional identifier for the 453 device. 455 ma-preconfig-credentials: The security credentials used by the 456 measurement agent. 458 3.2. Configuration Information 460 During registration or at any later point at which the MA contacts 461 the Controller (or vice-versa), the choice of Controller, details for 462 the timing of communication with the Controller or parameters for the 463 communication Task(s) can be changed (as captured by the Channels, 464 Schedules and Task Configurations objects). For example the pre- 465 configured Controller (specified as a Channel or Channels) may be 466 over-ridden with a specific Controller that is more appropriate to 467 the MA device type, location or characteristics of the network (e.g., 468 access technology type or broadband product). The initial 469 communication Schedule may be over-ridden with one more relevant to 470 routine communications between the MA and the Controller. 472 While some Control protocols may only use a single Schedule, other 473 protocols may use several Schedules (and related data transfer Tasks) 474 to update the Configuration Information, transfer the Instruction 475 Information, transfer Capability and Status Information and send 476 other information to the Controller such as log or error 477 notifications. Multiple Channels may be used to communicate with the 478 same Controller over multiple interfaces (e.g., to send logging 479 information over a different network). 481 In addition the MA will be given further items of information that 482 relate specifically to the MA rather than the measurements it is to 483 conduct or how to report results. The assignment of an ID to the MA 484 is mandatory. If the MA Agent ID was not optionally provided during 485 the pre-configuration then one must be provided by the Controller 486 during Configuration. Optionally a Group ID may also be given which 487 identifies a group of interest to which that MA belongs. For example 488 the group could represent an ISP, broadband product, technology, 489 market classification, geographic region, or a combination of 490 multiple such characteristics. Where the Measurement Group ID is set 491 an additional flag (the Report MA ID flag) is required to control 492 whether the Measurement Agent ID is also to be reported. The 493 reporting of a Group ID without the MA ID allows the MA to remain 494 anonymous, which may be particularly useful to prevent tracking of 495 mobile MA devices. 497 Optionally an MA can also be configured to stop executing any 498 Instruction Schedule if the Controller is unreachable. This can be 499 used as a fail-safe to stop Measurement and other Tasks being 500 conducted when there is doubt that the Instruction Information is 501 still valid. This is simply represented as a time window in seconds 502 since the last communication with the Controller after which an Event 503 is generated that can trigger the suspension of Instruction 504 Schedules. The appropriate value of the time window will depend on 505 the specified communication Schedule with the Controller and the 506 duration for which the system is willing to tolerate continued 507 operation with potentially stale Instruction Information. 509 While Pre-Configuration Information is persistent upon device reset 510 or power cycle, the persistency of the Configuration Information may 511 be device dependent. Some devices may revert back to their pre- 512 configuration state upon reboot or factory reset, while other devices 513 may store all Configuration and Instruction information in persistent 514 storage. A Controller can check whether an MA has the latest 515 Configuration and Instruction information by examining the Capability 516 and Status information for the MA. 518 3.2.1. Definition of ma-config-obj 519 object { 520 uuid ma-config-agent-id; 521 ma-task-obj ma-config-control-tasks<1..*>; 522 ma-channel-obj ma-config-control-channels<1..*>; 523 ma-schedule-obj ma-config-control-schedules<1..*>; 524 [uri ma-config-device-id;] 525 credentials ma-config-credentials; 526 [string ma-config-group-id;] 527 [string ma-config-measurement-point;] 528 [boolean ma-config-report-agent-id;] 529 [boolean ma-config-report-measurement-point;] 530 [int ma-config-controller-timeout;] 531 } ma-config-obj; 533 The ma-config-obj consists of the following elements: 535 ma-config-agent-id: A uuid uniquely identifying the 536 measurement agent. 538 ma-config-control-tasks: An unordered set of task objects. 540 ma-config-control-channels: An unordered set of channel 541 objects. 543 ma-config-control-schedules: An unordered set of scheduling 544 objects. 546 ma-config-device-id: An optional identifier for the 547 device. 549 ma-config-credentials: The security credentials used by 550 the measurement agent. 552 ma-config-group-id: An optional identifier of the 553 group of measurement agents this 554 measurement agent belongs to. 556 ma-config-measurement-point: An optional identifier for the 557 measurement point indicating 558 where the measurement agent is 559 located on a path (see [RFC7398] 560 for further details). 562 ma-config-report-agent-id: An optional flag indicating 563 whether the identifier (ma- 564 config-agent-id) should be 565 included in reports. The default 566 value is false. 568 ma-config-report-measurement-point: An optional flag indicating 569 whether the measurement point 570 (ma-config-measurement-point) 571 should be included in reports. 572 The default value is false. 574 ma-config-controller-timeout: A timer is started after each 575 successful contact with a 576 controller. When the timer 577 reaches the controller-timeout 578 (measured in seconds), an event 579 is raised indicating that 580 connectivity to the controller 581 has been lost (see ma-controller- 582 lost-obj). 584 3.3. Instruction Information 586 The Instruction information model has four sub-elements: 588 1. Instruction Task Configurations 590 2. Report Channels 592 3. Instruction Schedules 594 4. Suppression 596 The Instruction supports the execution of all Tasks on the MA except 597 those that deal with communication with the Controller (specified in 598 (pre-)configuration information). The Tasks are configured in 599 Instruction Task Configurations and included by reference in 600 Instruction Schedules that specify when to execute them. The results 601 can be communicated to other Schedules or a Task may implement a 602 Reporting Protocol and communicate results over Report Channels. 603 Suppression is used to temporarily stop the execution of new Tasks as 604 specified by the Instruction Schedules (and optionally to stop 605 ongoing Tasks). 607 A Task Configuration is used to configure the mandatory and optional 608 parameters of a Task. It also serves to instruct the MA about the 609 Task including the ability to resolve the Task to an executable and 610 specifying the schema for the Task parameters. 612 A Report Channel defines how to communicate with a single remote 613 system specified by a URL. A Report Channel is used to send results 614 to a single Collector but is no different in terms of the Information 615 Model to the Control Channel used to transfer information between the 616 MA and the Controller. Several Report Channels can be defined to 617 enable results to be split or duplicated across different 618 destinations. A single Channel can be used by multiple (reporting) 619 Task Configurations to transfer data to the same Collector. A single 620 Reporting Task Configuration can also be included in multiple 621 Schedules. E.g., a single Collector may receive data at three 622 different cycle rates, one Schedule reporting hourly, another 623 reporting daily and a third specifying that results should be sent 624 immediately for on-demand measurement tasks. Alternatively multiple 625 Report Channels can be used to send Measurement Task results to 626 different Collectors. The details of the Channel element is 627 described later as it is common to several objects. 629 Instruction Schedules specify which Actions to execute according to a 630 given triggering Event. An Action is a Task with additional specific 631 parameters. An Event can trigger the execution of a single Action or 632 it can trigger a repeated series of Actions. The Schedule also 633 specifies how to link Tasks output data to other Schedules. 635 Measurement Suppression information is used to over-ride the 636 Instruction Schedule and temporarily stop measurements or other Tasks 637 from running on the MA for a defined or indefinite period. While 638 conceptually measurements can be stopped by simply removing them from 639 the Measurement Schedule, splitting out separate information on 640 Measurement Suppression allows this information to be updated on the 641 MA on a different timing cycle or protocol implementation to the 642 Measurement Schedule. It is also considered that it will be easier 643 for a human operator to implement a temporary explicit suppression 644 rather than having to move to a reduced Schedule and then roll-back 645 at a later time. 647 It should be noted that control schedules and tasks cannot be 648 suppressed as evidenced by the lack of suppression information in the 649 Configuration. The control schedule must only reference tasks listed 650 as control tasks (i.e., within the Configuration information). 652 A single Suppression object is able to enable/disable a set of 653 Instruction Tasks that are tagged for suppression. This enabled fine 654 grained control on which Tasks are suppressed. Suppression of both 655 matching Actions and Measurement Schedules is supported. Support for 656 disabling specific Actions allows malfunctioning or mis-configured 657 Tasks or Actions that have an impact on a particular part of the 658 network infrastructure (e.g., a particular Measurement Peer) to be 659 targeted. Support for disabling specific Schedules allows for 660 particularly heavy cycles or sets of less essential Measurement Tasks 661 to be suppressed quickly and effectively. Note that Suppression has 662 no effect on either Controller Tasks or Controller Schedules. 664 Suppression stops new Tasks from executing. In addition, the 665 Suppression information also supports an additional Boolean that is 666 used to select whether on-going tasks are also to be terminated. 668 Unsuppression is achieved through either overwriting the Measurement 669 Suppression information (e.g., changing 'enabled' to False) or 670 through the use of an End time such that the Measurement Suppression 671 will no longer be in effect beyond this time. The datetime format 672 used for all elements in the information model (e.g., the suppression 673 start and end dates) MUST conform to RFC 3339 [RFC3339]. 675 The goal when defining these four different elements is to allow each 676 part of the information model to change without affecting the other 677 three elements. For example it is envisaged that the Report Channels 678 and the set of Task Configurations will be relatively static. The 679 Instruction Schedule, on the other hand, is likely to be more 680 dynamic, as the measurement panel and test frequency are changed for 681 various business goals. Another example is that measurements can be 682 suppressed with a Suppression command without removing the existing 683 Instruction Schedules that would continue to apply after the 684 Suppression expires or is removed. In terms of the Controller-MA 685 communication this can reduce the data overhead. It also encourages 686 the re-use of the same standard Task Configurations and Reporting 687 Channels to help ensure consistency and reduce errors. 689 3.3.1. Definition of ma-instruction-obj 691 object { 692 ma-task-obj ma-instruction-tasks<0..*>; 693 ma-channel-obj ma-instruction-channels<0..*>; 694 ma-schedule-obj ma-instruction-schedules<0..*>; 695 [ma-suppression-obj ma-instruction-suppressions<0..*>;] 696 } ma-instruction-obj; 698 An ma-instruction-obj consists of the following elements: 700 ma-instruction-tasks: A possibly empty unordered set of task 701 objects. 703 ma-instruction-channels: A possibly empty unordered set of 704 channel objects. 706 ma-instruction-schedules: A possibly empty unordered set of 707 schedule objects. 709 ma-instruction-suppressions: An optional possibly empty unordered 710 set of suppression objects. 712 3.3.2. Definition of ma-suppression-obj 714 object { 715 string ma-suppression-name; 716 [ma-event-obj ma-suppression-start;] 717 [ma-event-obj ma-suppression-end;] 718 [string ma-suppression-match<0..*>;] 719 [boolean ma-suppression-stop-running;] 720 } ma-suppression-obj; 722 The ma-suppression-obj controls the suppression of schedules or 723 actions and consists of the following elements: 725 ma-suppression-name: A name uniquely identifying a 726 suppression. 728 ma-suppression-start: The optional event indicating when 729 suppression starts. If not present, 730 the suppression starts immediately, 731 i.e., as if the value would be 732 'immediate'. 734 ma-suppression-end: The optional event indicating when 735 suppression ends. If not present, the 736 suppression does not have a defined 737 end, i.e., the suppression remains for 738 an indefinite period of time. 740 ma-suppression-match: An optional and possibly empty 741 unordered set of match patterns. The 742 suppression will apply to all schedules 743 (and their actions) that have a 744 matching value in their ma-schedule- 745 suppression-tags and all actions that 746 have a matching value in their ma- 747 action-suppression-tags. Pattern 748 matching is done using glob style 749 pattern (see below). 751 ma-suppression-stop-running: An optional boolean indicating whether 752 suppression will stop any running 753 matching schedules or actions. The 754 default value for this boolean is 755 false. 757 Glob style pattern matching is following POSIX.2 fnmatch() without 758 special treatment of file paths: 760 * matches a sequence of characters 761 ? matches a single character 762 [seq] matches any character in seq 763 [!seq] matches any character not in seq 765 A backslash followed by a character matches the following character. 766 In particular: 768 \* matches * 769 \? matches ? 770 \\ matches \ 772 A sequence seq may be a sequence of characters (e.g., [abc] or a 773 range of characters (e.g., [a-c]). 775 3.4. Logging Information 777 The MA may report on the success or failure of Configuration or 778 Instruction communications from the Controller. In addition further 779 operational logs may be produced during the operation of the MA and 780 updates to capabilities may also be reported. Reporting this 781 information is achieved in exactly the same manner as scheduling any 782 other Task. We make no distinction between a Measurement Task 783 conducting an active or passive network measurement and one which 784 solely retrieves static or dynamic information from the MA such as 785 capabilities or logging information. One or more logging tasks can 786 be programmed or configured to capture subsets of the Logging 787 Information. These logging tasks are then executed by Schedules 788 which also specify that the resultant data is to be transferred over 789 the Controller Channels. 791 The type of Logging Information will fall into three different 792 categories: 794 1. Success/failure/warning messages in response to information 795 updates from the Controller. Failure messages could be produced 796 due to some inability to receive or parse the Controller 797 communication, or if the MA is not able to act as instructed. 798 For example: 800 * "Measurement Schedules updated OK" 802 * "Unable to parse JSON" 804 * "Missing mandatory element: Measurement Timing" 806 * "'Start' does not conform to schema - expected datetime" 807 * "Date specified is in the past" 809 * "'Hour' must be in the range 1..24" 811 * "Schedule A refers to non-existent Measurement Task 812 Configuration" 814 * "Measurement Task Configuration X registry entry Y not found" 816 * "Updated Measurement Task Configurations do not include M used 817 by Measurement Schedule N" 819 2. Operational updates from the MA. For example: 821 * "Out of memory: cannot record result" 823 * "Collector 'collector.example.com' not responding" 825 * "Unexpected restart" 827 * "Suppression timeout" 829 * "Failed to execute Measurement Task Configuration H" 831 3. Status updates from the MA. For example: 833 * "Device interface added: eth3" 835 * "Supported measurements updated" 837 * "New IP address on eth0: xxx.xxx.xxx.xxx" 839 This Information Model document does not detail the precise format of 840 logging information since it is to a large extent protocol and MA 841 specific. However, some common information can be identified. 843 3.4.1. Definition of ma-log-obj 845 object { 846 uuid ma-log-agent-id; 847 datetime ma-log-event-time; 848 code ma-log-code; 849 string ma-log-description; 850 } ma-log-obj; 852 The ma-log-obj models the generic aspects of a logging object and 853 consists of the following elements: 855 ma-log-agent-id: A uuid uniquely identifying the measurement 856 agent. 858 ma-log-event-time: The date and time of the event reported in 859 the logging object. 861 ma-log-code: A machine readable code describing the 862 event. 864 ma-log-description: A human readable description of the event. 866 3.5. Capability and Status Information 868 The MA will hold Capability Information that can be retrieved by a 869 Controller. Capabilities include the device interface details 870 available to Measurement Tasks as well as the set of Measurement 871 Tasks/Roles (specified by registry entries) that are actually 872 installed or available on the MA. Status information includes the 873 times that operations were last performed such as contacting the 874 Controller or producing Reports. 876 3.5.1. Definition of ma-capability-obj 878 object { 879 string ma-capability-hardware; 880 string ma-capability-firmware; 881 string ma-capability-version; 882 [string ma-capability-tags<0..*>;] 883 [ma-capability-task-obj ma-capability-tasks<0..*>;] 884 } ma-capability-obj; 886 The ma-capability-obj provides information about the capabilities of 887 the measurement agent and consists of the following elements: 889 ma-capability-hardware: A description of the hardware of the device 890 the measurement agent is running on. 892 ma-capability-firmware: A description of the firmware of the device 893 the measurement agent is running on. 895 ma-capability-version: The version of the measurement agent. 897 ma-capability-tags: An optional unordered set of tags that 898 provide additional information about the 899 capabilities of the measurement agent. 901 ma-capability-tasks: An optional unordered set of capability 902 objects for each supported task. 904 3.5.2. Definition of ma-capability-task-obj 906 object { 907 string ma-capability-task-name; 908 ma-metric-registry-obj ma-capability-task-metrics<0..*>; 909 string ma-capability-task-version; 910 } ma-capability-task-obj; 912 The ma-capability-task-obj provides information about the capability 913 of a task and consists of the following elements: 915 ma-capability-task-name: A name uniquely identifying a task. 917 ma-capability-task-metrics: A possibly empty unordered set of 918 registered metrics and associated roles 919 this task implements. 921 ma-capability-task-version: The version of the measurement task. 923 3.5.3. Definition of ma-status-obj 925 object { 926 uuid ma-status-agent-id; 927 uri ma-status-device-id; 928 datetime ma-status-last-started; 929 ma-status-interface-obj ma-status-interfaces<0..*>; 930 [ma-status-schedule-obj ma-status-schedules<0..*>;] 931 [ma-status-suppression-obj ma-status-suppressions<0..*>;] 932 } ma-status-obj; 934 The ma-status-obj provides status information about the measurement 935 agent and consists of the following elements: 937 ma-status-agent-id: A uuid uniquely identifying the measurement 938 agent. 940 ma-status-device-id: A URI identifying the device. 942 ma-status-last-started: The date and time the measurement agent 943 last started. 945 ma-status-interfaces: An unordered set of network interfaces 946 available on the device. 948 ma-status-schedules: An optional unordered set of status objects 949 for each schedule. 951 ma-status-suppressions: An optional unordered set of status objects 952 for each suppression. 954 3.5.4. Definition of ma-status-schedule-obj 956 object { 957 string ma-status-schedule-name; 958 string ma-status-schedule-state; 959 int ma-status-schedule-storage; 960 counter ma-status-schedule-invocations; 961 counter ma-status-schedule-suppressions; 962 counter ma-status-schedule-overlaps; 963 counter ma-status-schedule-failures; 964 datetime ma-status-schedule-last-invocation; 965 [ma-status-action-obj ma-status-schedule-actions<0..*>;] 966 } ma-status-schedule-obj; 968 The ma-status-schedule-obj provides status information about the 969 status of a schedule and consists of the following elements: 971 ma-status-schedule-name: The name of the schedule this 972 status object refers to. 974 ma-status-schedule-state: The state of the schedule. The 975 value 'enabled' indicates that 976 the schedule is currently 977 enabled. The value 'suppressed' 978 indicates that the schedule is 979 currently suppressed. The value 980 'disabled' indicates that the 981 schedule is currently disabled. 982 The value 'running' indicates 983 that the schedule is currently 984 running. 986 ma-status-schedule-storage: The amount of secondary storage 987 (e.g., allocated in a file 988 system) holding temporary data 989 allocated to the schedule in 990 bytes. This object reports the 991 amount of allocated physical 992 storage and not the storage used 993 by logical data records. Data 994 models should use a 64-bit 995 integer type. 997 ma-status-schedule-invocations Number of invocations of this 998 schedule. This counter does not 999 include suppressed invocations or 1000 invocations that were prevented 1001 due to an overlap with a previous 1002 invocation of this schedule. 1004 ma-status-schedule-suppressions Number of suppressed executions 1005 of this schedule. 1007 ma-status-schedule-overlaps Number of executions prevented 1008 due to overlaps with a previous 1009 invocation of this schedule. 1011 ma-status-schedule-failures Number of failed executions of 1012 this schedule. A failed 1013 execution is an execution where 1014 at least one action failed. 1016 ma-status-schedule-last-invocation: The date and time of the last 1017 invocation of this schedule. 1019 ma-status-schedule-actions: An optional ordered list of 1020 status objects for each action of 1021 the schedule. 1023 3.5.5. Definition of ma-status-action-obj 1025 object { 1026 string ma-status-action-name; 1027 string ma-status-action-state; 1028 int ma-status-action-storage; 1029 counter ma-status-action-invocations; 1030 counter ma-status-action-suppressions; 1031 counter ma-status-action-overlaps; 1032 counter ma-status-action-failures; 1033 datetime ma-status-action-last-invocation; 1034 datetime ma-status-action-last-completion; 1035 int ma-status-action-last-status; 1036 string ma-status-action-last-message; 1037 datetime ma-status-action-last-failed-completion; 1038 int ma-status-action-last-failed-status; 1039 string ma-status-action-last-failed-message; 1040 } ma-status-action-obj; 1042 The ma-status-action-obj provides status information about an action 1043 of a schedule and consists of the following elements: 1045 ma-status-action-name: The name of the action of a 1046 schedule this status object 1047 refers to. 1049 ma-status-action-state: The state of the action. 1050 The value 'enabled' 1051 indicates that the action is 1052 currently enabled. The 1053 value 'suppressed' indicates 1054 that the action is currently 1055 suppressed. The value 1056 'disabled' indicates that 1057 the action is currently 1058 disabled. The value 1059 'running' indicates that the 1060 action is currently running. 1062 ma-status-action-storage: The amount of secondary 1063 storage (e.g., allocated in 1064 a file system) holding 1065 temporary data allocated to 1066 the action in bytes. This 1067 object reports the amount of 1068 allocated physical storage 1069 and not the storage used by 1070 logical data records. Data 1071 models should use a 64-bit 1072 integer type. 1074 ma-status-action-invocations Number of invocations of 1075 this action. This counter 1076 does not include suppressed 1077 invocations or invocations 1078 that were prevented due to 1079 an overlap with a previous 1080 invocation of this action. 1082 ma-status-action-suppressions Number of suppressed 1083 executions of this action. 1085 ma-status-action-overlaps Number of executions 1086 prevented due to overlaps 1087 with a previous invocation 1088 of this action. 1090 ma-status-action-failures Number of failed executions 1091 of this action. 1093 ma-status-action-last-invocation: The date and time of the 1094 last invocation of this 1095 action. 1097 ma-status-action-last-completion: The date and time of the 1098 last completion of this 1099 action. 1101 ma-status-action-last-status: The status code returned by 1102 the last execution of this 1103 action. 1105 ma-status-action-last-message: The status message produced 1106 by the last execution of 1107 this action. 1109 ma-status-action-last-failed-completion: The date and time of the 1110 last failed completion of 1111 this action. 1113 ma-status-action-last-failed-status: The status code returned by 1114 the last failed execution of 1115 this action. 1117 ma-status-action-last-failed-message: The status message produced 1118 by the last failed execution 1119 of this action. 1121 3.5.6. Definition of ma-status-suppression-obj 1123 object { 1124 string ma-status-suppression-name; 1125 string ma-status-suppression-state; 1126 } ma-status-suppression-obj; 1128 The ma-status-suppression-obj provides status information about that 1129 status of a suppression and consists of the following elements: 1131 ma-status-schedule-name: The name of the suppression this status 1132 object refers to. 1134 ma-status-schedule-state: The state of the suppression. The value 1135 'enabled' indicates that the suppression 1136 is currently enabled. The value 'active 1137 indicates that the suppression is 1138 currently active. The value 'disabled' 1139 indicates that the suppression is 1140 currently disabled. 1142 3.5.7. Definition of ma-status-interface-obj 1144 object { 1145 string ma-status-interface-name; 1146 string ma-status-interface-type; 1147 [int ma-status-interface-speed;] 1148 [string ma-status-interface-link-layer-address;] 1149 [ip-address ma-status-interface-ip-addresses<0..*>;] 1150 [ip-address ma-status-interface-gateways<0..*>;] 1151 [ip-address ma-status-interface-dns-servers<0..*>;] 1152 } ma-status-interface-obj; 1154 The ma-status-interface-obj provides status information about network 1155 interfaces and consists of the following elements: 1157 ma-status-interface-name: A name uniquely identifying a 1158 network interface. 1160 ma-status-interface-type: The type of the network 1161 interface. 1163 ma-status-interface-speed: An optional indication of the 1164 speed of the interface 1165 (measured in bits-per- 1166 second). 1168 ma-status-interface-link-layer-address: An optional link-layer 1169 address of the interface. 1171 ma-status-interface-ip-addresses: An optional ordered list of 1172 IP addresses assigned to the 1173 interface. 1175 ma-status-interface-gateways: An optional ordered list of 1176 gateways assigned to the 1177 interface. 1179 ma-status-interface-dns-servers: An optional ordered list of 1180 DNS servers assigned to the 1181 interface. 1183 3.6. Reporting Information 1185 At a point in time specified by a Schedule, the MA will execute tasks 1186 that communicate a set of measurement results to the Collector. 1187 These Reporting Tasks will be configured to transmit task results 1188 over a specified Report Channel to a Collector. 1190 It should be noted that the output from Tasks does not need to be 1191 sent to communication Channels. It can alternatively, or 1192 additionally, be sent to other Tasks on the MA. This facilitates 1193 using a first Measurement Task to control the operation of a later 1194 Measurement Task (such as first probing available line speed and then 1195 adjusting the operation of a video testing measurement) and also to 1196 allow local processing of data to output alarms (e.g., when 1197 performance drops from earlier levels). Of course, subsequent Tasks 1198 also include Tasks that implement the reporting protocol(s) and 1199 transfer data to one or more Collector(s). 1201 The Report generated by a Reporting Task is structured hierarchically 1202 to avoid repetition of report header and Measurement Task 1203 Configuration information. The report starts with the timestamp of 1204 the report generation on the MA and details about the MA including 1205 the optional Measurement Agent ID and Group ID (controlled by the 1206 Configuration Information). 1208 Much of the report Information is optional and will depend on the 1209 implementation of the Reporting Task and any parameters defined in 1210 the Task Configuration for the Reporting Task. For example some 1211 Reporting Tasks may choose not to include the Measurement Task 1212 Configuration or Action parameters, while others may do so dependent 1213 on the Controller setting a configurable parameter in the Task 1214 Configuration. 1216 It is possible for a Reporting Task to send just the Report header 1217 (datetime and optional agent ID and/or Group ID) if no measurement 1218 data is available. Whether to send such empty reports again is 1219 dependent on the implementation of the Reporting Task and potential 1220 Task Configuration parameter. 1222 The handling of measurement data on the MA before generating a Report 1223 and transfer from the MA to the Collector is dependent on the 1224 implementation of the device, MA and/or scheduled Tasks and not 1225 defined by the LMAP standards. Such decisions may include limits to 1226 the measurement data storage and what to do when such available 1227 storage becomes depleted. It is generally suggested that 1228 implementations running out of storage stop executing new measurement 1229 tasks and retain old measurement data. 1231 No context information, such as line speed or broadband product are 1232 included within the report header information as this data is 1233 reported by individual tasks at the time they execute. Either a 1234 Measurement Task can report contextual parameters that are relevant 1235 to that particular measurement, or specific tasks can be used to 1236 gather a set of contextual and environmental data at certain times 1237 independent of the reporting schedule. 1239 After the report header information the results are reported grouped 1240 according to different Measurement Task Configurations. Each Task 1241 section optionally starts with replicating the Measurement Task 1242 Configuration information before the result headers (titles for data 1243 columns) and the result data rows. The Options reported are those 1244 used for the scheduled execution of the Measurement Task and 1245 therefore include the Options specified in the Task Configuration as 1246 well as additional Options specified in the Action. The Action 1247 Options are appended to the Task Configuration Options in exactly the 1248 same order as they were provided to the Task during execution. 1250 The result row data includes a time for the start of the measurement 1251 and optionally an end time where the duration also needs to be 1252 considered in the data analysis. 1254 Some Measurement Tasks may optionally include an indication of the 1255 cross-traffic although the definition of cross-traffic is left up to 1256 each individual Measurement Task. Some Measurement Tasks may also 1257 output other environmental measures in addition to cross-traffic such 1258 as CPU utlilisation or interface speed. 1260 Where the Configuration and Instruction information represent 1261 information transmitted via the Control Protocol, the Report 1262 represents the information that is transmitted via the Report 1263 Protocol. It is constructed at the time of sending a report and 1264 represents the inherent structure of the information that is sent to 1265 the Collector. 1267 3.6.1. Definition of ma-report-obj 1269 object { 1270 datetime ma-report-date; 1271 [uuid ma-report-agent-id;] 1272 [string ma-report-group-id;] 1273 [string ma-report-measurement-point;] 1274 [ma-report-result-obj ma-report-results<0..*>;] 1275 } ma-report-obj; 1277 The ma-report-obj provides the meta-data of a single report and 1278 consists of the following elements: 1280 ma-report-date: The date and time when the report was 1281 sent to a collector. 1283 ma-report-agent-id: An optional uuid uniquely identifying 1284 the measurement agent. 1286 ma-report-group-id: An optional identifier of the group of 1287 measurement agents this measurement 1288 agent belongs to. 1290 ma-report-measurement-point: An optional identifier for the 1291 measurement point indicating where the 1292 measurement agent is located on a path 1293 (see [RFC7398] for further details). 1295 ma-report-results: An optional and possibly empty 1296 unordered set of result objects. 1298 3.6.2. Definition of ma-report-result-obj 1300 object { 1301 string ma-report-result-schedule-name; 1302 string ma-report-result-action-name; 1303 string ma-report-result-task-name; 1304 [ma-option-obj ma-report-result-options<0..*>;] 1305 [string ma-report-result-tags<0..*>;] 1306 datetime ma-report-result-event-time; 1307 datetime ma-report-result-start-time; 1308 [datetime ma-report-result-end-time;] 1309 [string ma-report-result-cycle-number;] 1310 int ma-report-result-status; 1311 [ma-report-conflict-obj ma-report-result-conflicts<0..*>;] 1312 [ma-report-table-obj ma-report-result-tables<0..*>;] 1313 } ma-report-result-obj; 1315 The ma-report-result-obj provides the meta-data of a result report of 1316 a single executed action. It consists of the following elements: 1318 ma-report-result-schedule-name: The name of the schedule that 1319 produced the result. 1321 ma-report-result-action-name: The name of the action in the 1322 schedule that produced the result. 1324 ma-report-result-task-name: The name of the task that produced 1325 the result. 1327 ma-report-result-options: An optional ordered joined list of 1328 options provided by the task object 1329 and the action object when the action 1330 was started. 1332 ma-report-result-tags: An optional unordered set of tags. 1333 This is the joined set of tags 1334 provided by the task object and the 1335 action object and schedule object 1336 when the action was started. 1338 ma-report-result-event-time: The date and time of the event that 1339 triggerent the schedule of the action 1340 that produced the reported result 1341 values. The date and time does not 1342 include any added randomization. 1344 ma-report-result-start-time: The date and time of the start of the 1345 action that produced the reported 1346 result values. 1348 ma-report-result-end-time: An optional date and time indicating 1349 when the action finished. 1351 ma-report-result-cycle-number: An optional cycle number derived from 1352 ma-report-result-event-time. It is 1353 the time closest to ma-report-result- 1354 event-time that is a multiple of the 1355 ma-event-cycle-interval of the event 1356 that triggered the execution of the 1357 schedule. The value is only present 1358 in an ma-report-result-obj if the 1359 event that triggered the execution of 1360 the schedule has a defined ma-event- 1361 cycle-interval. The cycle number is 1362 represented in the format 1363 YYYYMMDD.HHMMSS where YYYY represents 1364 the year, MM the month (1..12), DD 1365 the day of the months (01..31), HH 1366 the hour (00..23), MM the minute 1367 (00..59), and SS the second (00..59). 1369 ma-report-result-status: The status code returned by the 1370 execution of the action. 1372 ma-report-result-conflicts: A possibly empty set of conflict 1373 actions that might have impacted the 1374 measurement results being reported. 1376 ma-report-result-tables: An optional and possibly empty 1377 unordered set of result tables. 1379 3.6.3. Definition of ma-report-conflict-obj 1381 object { 1382 string ma-report-conflict-schedule-name; 1383 string ma-report-conflict-action-name; 1384 string ma-report-conflict-task-name; 1385 } ma-report-conflict-obj; 1387 The ma-report-conflict-obj provides the information about conflicting 1388 action that might have impacted the measurement results. It consists 1389 of the following elements: 1391 ma-report-result-schedule-name: The name of the schedule that may 1392 have impacted the result. 1394 ma-report-result-action-name: The name of the action in the 1395 schedule that may have impacted the 1396 result. 1398 ma-report-result-task-name: The name of the task that may have 1399 impacted the result. 1401 3.6.4. Definition of ma-report-table-obj 1403 object { 1404 [ma-metric-registry-obj ma-report-table-metrics<0..*>;] 1405 [string] ma-report-table-column-labels<0..*>;] 1406 [ma-report-row-obj ma-report-table-rows<0..*>;] 1407 } ma-report-table-obj; 1409 The ma-report-table-obj represents a result table and consists of the 1410 following elements: 1412 ma-report-table-metrics: An optional and possibly empty 1413 unordered set of registered metrics 1414 and associated roles that are 1415 reported. 1417 ma-report-table-column-labels: An optional and possibly empty 1418 ordered list of column labels. 1420 ma-report-table-rows: A possibly empty ordered list of 1421 result rows. 1423 3.6.5. Definition of ma-report-row-obj 1425 object { 1426 data ma-report-row-values<0..*>; 1427 } ma-report-row-obj; 1429 The ma-report-row-obj represents a result row and consists of the 1430 following elements: 1432 ma-report-row-values: A possibly empty ordered list of result 1433 values. When present, it contains an 1434 ordered list of values that align to the 1435 set of column labels for the report. 1437 3.7. Common Objects: Schedules 1439 A Schedule specifies the execution of a single or repeated series of 1440 Actions. An Action is a Task with additional specific parameters. 1441 Each Schedule contains basically two elements: an ordered list of 1442 Actions to be executed and an Event object triggering the execution 1443 of the Schedule. The Schedule states what Actions to run (with what 1444 configuration) and when to run the Actions. A Schedule may 1445 optionally have an Event that stops the execution of the Schedule or 1446 a maximum duration after which a schedule is stopped. 1448 Multiple Actions contained as an ordered list of a single Measurement 1449 Schedule will be executed according to the execution mode of the 1450 Schedule. In sequential mode, Actions will be executed sequentially 1451 and in parallel mode, all Actions will be executed concurrently. In 1452 pipelined mode, data produced by one Action is passed to the 1453 subsequent Action. Actions contained in different Schedules execute 1454 in parallel with such conflicts being reported in the Reporting 1455 Information where necessary. If two or more Schedules have the same 1456 start time, then the two will execute in parallel. There is no 1457 mechanism to prioritise one schedule over another or to mutex 1458 scheduled tasks. 1460 As well as specifying which Actions to execute, the Schedule also 1461 specifies how to link the data outputs from each Action to other 1462 Schedules. Specifying this within the Schedule allows the highest 1463 level of flexibility since it is even possible to send the output 1464 from different executions of the same Task Configuration to different 1465 destinations. A single Task producing multiple different outputs is 1466 expected to properly tag the different result. An Action receiving 1467 the output can then filter the results based on the tag if necessary. 1468 For example, a Measurement Task might report routine results to a 1469 data Reporting Task in a Schedule that communicates hourly via the 1470 Broadband PPP interface, but also outputs emergency conditions via an 1471 alarm Reporting Task in a different Schedule communicating 1472 immediately over a GPRS channel. Note that task-to-task data 1473 transfer is always specified in association with the scheduled 1474 execution of the sending task - there is no need for a corresponding 1475 input specification for the receiving task. While it is likely that 1476 an MA implementation will use a queue mechanism between the Schedules 1477 or Actions, this Information Model does not mandate or define a 1478 queue. The Information Model, however, reports the storage allocated 1479 to Schedules and Actions so that storage usage can be monitored. 1480 Furthermore, it is recommended that MA implementations by default 1481 retain old data and stop the execution of new measurement tasks if 1482 the MA runs out of storage capacity. 1484 When specifying the task to execute within the Schedule, i.e., 1485 creating an Action, it is possible to add to the Action option 1486 parameters. This allows the Task Configuration to determine the 1487 common characteristics of a Task, while selected parameters (e.g., 1488 the test target URL) are defined within as option parameters of the 1489 Action in the schedule. A single Tasks Configuration can even be 1490 used multiple times in the same schedule with different additional 1491 parameters. This allows for efficiency in creating and transferring 1492 the Instruction. Note that the semantics of what happens if an 1493 option is defined multiple times (either in the Task Configuration, 1494 Action or in both) is not standardised and will depend upon the Task. 1495 For example, some tasks may legitimately take multiple values for a 1496 single parameter. 1498 Where Options are specified in both the Schedule and the Task 1499 Configuration, the Schedule Options are appended to those specified 1500 in the Task Configuration. 1502 Example: An Action of a Schedule references a single Measurement 1503 Task Configuration for measuring UDP latency. It specifies that 1504 results are to be sent to a Schedule with a Reporting Action. 1505 This Reporting Task of the Reporting Action is executed by a 1506 separate Schedule that specifies that it should run hourly at 5 1507 minutes past the hour. When run this Reporting Action takes the 1508 data generated by the UDP latency Measurement Task as well as any 1509 other data to be included in the hourly report and transfers it to 1510 the Collector over the Report Channel specified within its own 1511 Schedule. 1513 Schedules and Actions may optionally also be given tags that are 1514 included in result reports sent to a Collector. In addition, 1515 schedules can be given suppression tags that may be used to select 1516 Schedules and Actions for suppression. 1518 3.7.1. Definition of ma-schedule-obj 1520 object { 1521 string ma-schedule-name; 1522 ma-event-obj ma-schedule-start; 1523 [ma-event-obj ma-schedule-end;] 1524 [int ma-schedule-duration;] 1525 ma-action-obj ma-schedule-actions<0..*>; 1526 string ma-schedule-execution-mode; 1527 [string ma-schedule-tags<0..*>;] 1528 [string ma-schedule-suppression-tags<0..*>;] 1529 } ma-schedule-obj; 1531 The ma-schedule-obj is the main scheduling object. It consists of 1532 the following elements: 1534 ma-schedule-name: A name uniquely identifying a 1535 scheduling object. 1537 ma-schedule-start: An event object indicating when the 1538 schedule starts. 1540 ma-schedule-end: An optional event object controlling 1541 the forceful termination of scheduled 1542 actions. When the event occurs, all 1543 actions of the schedule will be forced 1544 to terminate gracefully. 1546 ma-schedule-duration: An optional duration in seconds for the 1547 schedule. All actions of the schedule 1548 will be forced to terminate gracefully 1549 after the duration number of seconds 1550 past the start of the schedule. 1552 ma-schedule-actions: A possibly empty ordered list of 1553 actions to invoke when the schedule 1554 starts. 1556 ma-schedule-execution-mode: Indicates whether the actions should be 1557 executed sequentially, in parallel, or 1558 in a pipelined mode (where data 1559 produced by one action is passed to the 1560 subsequent action). The default 1561 execution mode is pipelined. 1563 ma-schedule-tags: An optional unordered set of tags that 1564 are reported together with the 1565 measurement results to a collector. 1567 ma-schedule-suppression-tags: An optional unordered set of 1568 suppression tags that are used to 1569 select schedules to be suppressed. 1571 3.7.2. Definition of ma-action-obj 1573 object { 1574 string ma-action-name; 1575 string ma-action-config-task-name; 1576 [ma-option-obj ma-action-task-options<0..*>;] 1577 [string ma-action-destinations<0..*>;] 1578 [string ma-action-tags<0..*>;] 1579 [string ma-action-suppression-tags<0..*>;] 1580 } ma-action-obj; 1582 The ma-action-obj models a task together with its schedule specific 1583 task options and destination schedules. It consists of the following 1584 elements: 1586 ma-action-name: A name uniquely identifying an action 1587 of a scheduling object. 1589 ma-action-config-task-name: A name identifying the configured task 1590 to be invoked by the action. 1592 ma-action-task-options: An optional and possibly empty ordered 1593 list of options (name-value pairs) that 1594 are passed to the task by appending 1595 them to the options configured for the 1596 task object. 1598 ma-action-destinations: An optional and possibly empty 1599 unordered set of names of destination 1600 schedules that consume output produced 1601 by this action. 1603 ma-action-tags: An optional unordered set of tags that 1604 are reported together with the 1605 measurement results to a collector. 1607 ma-action-suppression-tags: An optional unordered set of 1608 suppression tags that are used to 1609 select actions to be suppressed. 1611 3.8. Common Objects: Channels 1613 A Channel defines a bi-directional communication channel between the 1614 MA and a Controller or Collector. Multiple Channels can be defined 1615 to enable results to be split or duplicated across different 1616 Collectors. 1618 Each Channel contains the details of the remote endpoint (including 1619 location and security credential information such as the 1620 certificate). The timing of when to communicate over a Channel is 1621 specified by the Schedule which executes the corresponding Control or 1622 Reporting Task. The certificate can be the digital certificate 1623 associated to the FQDN in the URL or it can be the certificate of the 1624 Certification Authority that was used to issue the certificate for 1625 the FQDN (Fully Qualified Domain Name) of the target URL (which will 1626 be retrieved later on using a communication protocol such as TLS). 1627 In order to establish a secure channel, the MA will use it's own 1628 security credentials (in the Configuration Information) and the given 1629 credentials for the individual Channel end-point. 1631 As with the Task Configurations, each Channel is also given a text 1632 name by which it can be referenced as a Task Option. 1634 Although the same in terms of information, Channels used for 1635 communication with the Controller are referred to as Control Channels 1636 whereas Channels to Collectors are referred to as Report Channels. 1637 Hence Control Channels will be referenced from Control Tasks executed 1638 by a Control Schedule, whereas Report Channels will be referenced 1639 from within Reporting Tasks executed by an Instruction Schedule. 1641 Multiple interfaces are also supported. For example the Reporting 1642 Task could be configured to send some results over GPRS. This is 1643 especially useful when such results indicate the loss of connectivity 1644 on a different network interface. 1646 Example: A Channel used for reporting results may specify that 1647 results are to be sent to the URL (https://collector.example.org/ 1648 report/), using the appropriate digital certificate to establish a 1649 secure channel. 1651 3.8.1. Definition of ma-channel-obj 1653 object { 1654 string ma-channel-name; 1655 url ma-channel-target; 1656 credentials ma-channel-credentials; 1657 [string ma-channel-interface-name;] 1658 } ma-channel-obj; 1660 The ma-channel-obj consists of the following elements: 1662 ma-channel-name: A unique name identifying the channel 1663 object. 1665 ma-channel-target: A URL identifying the target channel 1666 endpoint. 1668 ma-channel-credentials: The security credentials needed to 1669 establish a secure channel. 1671 ma-channel-interface-name: An optional name of the network interface 1672 to be used. If not present, the IP 1673 protocol stack will select a suitable 1674 interface. 1676 3.9. Common Objects: Task Configurations 1678 Conceptually each Task Configuration defines the parameters of a Task 1679 that the Measurement Agent (MA) may perform at some point in time. 1680 It does not by itself actually instruct the MA to perform them at any 1681 particular time (this is done by a Schedule). Tasks can be 1682 Measurement Tasks (i.e., those Tasks actually performing some type of 1683 passive or active measurement) or any other scheduled activity 1684 performed by the MA such as transferring information to or from the 1685 Controller and Collectors. Other examples of Tasks may include data 1686 manipulation or processing Tasks conducted on the MA. 1688 A Measurement Task Configuration is the same in information terms to 1689 any other Task Configuration. Both measurement and non-measurement 1690 Tasks have registry entries to enable the MA to uniquely identify the 1691 Task it should execute and retrieve the schema for any parameters 1692 that may be passed to the Task. Registry entries are specified as a 1693 URI and can therefore be used to identify the Task within a namespace 1694 or point to a web or local file location for the Task information. 1695 As mentioned previously, these URIs may be used to identify the 1696 Measurement Task in a public namespace 1697 [I-D.ietf-ippm-metric-registry]. 1699 Example: A Measurement Task Configuration may configure a single 1700 Measurement Task for measuring UDP latency. The Measurement Task 1701 Configuration could define the destination port and address for 1702 the measurement as well as the duration, internal packet timing 1703 strategy and other parameters (for example a stream for one hour 1704 and sending one packet every 500 ms). It may also define the 1705 output type and possible parameters (for example the output type 1706 can be the 95th percentile mean) where the measurement task 1707 accepts such parameters. It does not define when the task starts 1708 (this is defined by the Schedule element), so it does not by 1709 itself instruct the MA to actually perform this Measurement Task. 1711 The Task Configuration will include a local short name for reference 1712 by a Schedule. Task Configurations may also refer to registry 1713 entries as described above. In addition the Task can be configured 1714 through a set of configuration Options. The nature and number of 1715 these Options will depend upon the Task. These options are expressed 1716 as name-value pairs although the 'value' may be a structured object 1717 instead of a simple string or numeric value. The implementation of 1718 these name-value pairs will vary between data models. 1720 An Option that must be present for Reporting Tasks is the Channel 1721 reference specifying how to communicate with a Collector. This is 1722 included in the task options and will have a value that matches a 1723 channel name that has been defined in the Instruction. Similarly 1724 Control Tasks will have a similar option with the value set to a 1725 specified Control Channel. 1727 A Reporting Task might also have a flag parameter to indicate whether 1728 to send a report without measurement results if there is no 1729 measurement result data pending to be transferred to the Collector. 1730 In addition many tasks will also take as a parameter which interface 1731 to operate over. 1733 In addition the Task Configuration may optionally also be given tags 1734 that can carry a Measurement Cycle ID. The purpose of this ID is to 1735 easily identify a set of measurement results that have been produced 1736 by Measurement Tasks with comparable Options. This ID could be 1737 manually incremented or otherwise changed when an Option change is 1738 implemented which could mean that two sets of results should not be 1739 directly compared. 1741 3.9.1. Definition of ma-task-obj 1743 object { 1744 string ma-task-name; 1745 ma-metric-registry-obj ma-task-metrics<0..*>; 1746 [ma-option-obj ma-task-options<0..*>;] 1747 [string ma-task-tags<0..*>;] 1748 } ma-task-obj; 1750 The ma-task-obj defines a configured task that can be invoked as part 1751 of an action. A configured task can be referenced by its name and it 1752 contains a set of URIs to link to a metrics registry or a local 1753 specification of the task. Options allow the configuration of task 1754 parameters (in the form of name-value pairs). The ma-task-obj 1755 consists of the following elements: 1757 ma-task-name: A name uniquely identifying a 1758 configured task object. 1760 ma-task-metrics: A possibly empty unordered set of 1761 registered metrics and associated roles 1762 the configured measurement task will 1763 use. 1765 ma-task-options: An optional and possibly empty ordered 1766 list of options (name-value pairs) that 1767 are passed to the configured task. 1769 ma-task-tags: An optional unordered set of tags that 1770 are reported together with the 1771 measurement results to a collector. 1773 3.9.2. Definition of ma-option-obj 1775 object { 1776 string ma-option-name; 1777 [object ma-option-value;] 1778 } ma-option-obj; 1780 The ma-option-obj models a name-value pair and consists of the 1781 following elements: 1783 ma-option-name: The name of the option. 1785 ma-option-value: The optional value of the option. 1787 The ma-option-obj is used to define Task Configuration Options. Task 1788 Configuration Options are generally task specific. For tasks 1789 associated with an entry in a registry, the registry may define well- 1790 known option names (e.g., the so-called parameters in the IPPM metric 1791 registry [I-D.ietf-ippm-metric-registry]). Control and Reporting 1792 Tasks need to know the Channel they are going to use. The common 1793 option name for specifying the channel is "channel" where the 1794 option's value refers to the name of an ma-channel-obj. 1796 3.10. Common Objects: Registry Information 1798 Tasks and actions can be associated with entries in a metrics 1799 registry. A metric is identified by a URI and a metric may have 1800 associated roles. 1802 3.10.1. Definition of ma-metric-registry-obj 1804 object { 1805 uri ma-metric-registry-entry; 1806 [string ma-metric-registry-role<0..*>;] 1807 } ma-metric-registry-obj; 1809 The ma-metric-registry-obj defines a registered metric and the 1810 associated role(s). The ma-metric-registry-obj consists of the 1811 following elements: 1813 ma-metric-registry-entry: A URI identifying a metric in a metric 1814 registry. 1816 ma-metric-registry-role: An optional and possibly empty unordered 1817 set of roles for the metric. 1819 3.11. Common Objects: Event Information 1821 The Event information object used throughout the information models 1822 can initially take one of several different forms. Additional forms 1823 may be defined later in order to bind the execution of schedules to 1824 additional events. The initially defined Event forms are: 1826 1. Periodic Timing: Emits multiple events periodically according to 1827 an interval time defined in seconds 1829 2. Calendar Timing: Emits multiple events according to a calendar 1830 based pattern, e.g., 22 minutes past each hour of the day on 1831 weekdays 1833 3. One Off Timing: Emits one event at a specific date and time 1835 4. Immediate: Emits one event as soon as possible 1837 5. Startup: Emits an event whenever the MA is started (e.g., at 1838 device startup) 1840 6. Controller Lost: Emits an event when connectivity to the 1841 controller has been lost 1843 7. Controller Connected: Emits an event when connectivity to the 1844 controller has been (re-)established 1846 Optionally each of the Event options may also specify a randomness 1847 that should be evaluated and applied separately to each indicated 1848 event. This randomness parameter defines a uniform interval in 1849 seconds over which the start of the task is delayed from the starting 1850 times specified by the event object. 1852 Both the Periodic and Calendar timing objects allow for a series of 1853 Actions to be executed. While both have an optional end time, it is 1854 best practice to always configure an end time and refresh the 1855 information periodically to ensure that lost MAs do not continue 1856 their tasks forever. 1858 Startup events are only created on device startup, not when a new 1859 Instruction is transferred to the MA. If scheduled task execution is 1860 desired both on the transfer of the Instruction and on device restart 1861 then both the Immediate and Startup timing needs to be used in 1862 conjunction. 1864 The datetime format used for all elements in the information model 1865 MUST conform to RFC 3339 [RFC3339]. 1867 3.11.1. Definition of ma-event-obj 1869 object { 1870 string ma-event-name; 1871 union { 1872 ma-periodic-obj ma-event-periodic; 1873 ma-calendar-obj ma-event-calendar; 1874 ma-one-off-obj ma-event-one-off; 1875 ma-immediate-obj ma-event-immediate; 1876 ma-startup-obj ma-event-startup; 1877 ma-controller-lost-obj ma-event-controller-lost; 1878 ma-controller-connected-obj ma-event-controller-connected; 1879 } 1880 [int ma-event-random-spread;] 1881 [int ma-event-cycle-interval;] 1882 } ma-event-obj; 1884 The ma-event-obj is the main event object. Event objects are 1885 identified by a name. A generic event object itself contains a more 1886 specific event object. The set of specific event objects should be 1887 extensible. The initial set of specific event objects is further 1888 described below. The ma-event-obj also includes an optional uniform 1889 random spread that can be used to randomize the start times of 1890 schedules triggered by an event. The ma-event-obj consists of the 1891 following elements: 1893 ma-event-name: The name uniquely identifies an event 1894 object. Schedules refer to event 1895 objects by this name. 1897 ma-event-periodic: The ma-event-periodic is present for 1898 periodic timing objects. 1900 ma-event-calendar: The ma-event-calendar is present for 1901 calendar timing objects. 1903 ma-event-one-off: The ma-event-one-off is present for 1904 one-off timing objects. 1906 ma-event-immediate: The ma-event-immediate is present for 1907 immediate event objects. 1909 ma-event-startup: The ma-event-startup is present for 1910 startup event objects. 1912 ma-event-controller-lost: The ma-event-controller-lost is 1913 present for connectivity to 1914 controller lost event objects. 1916 ma-event-controller-connected: The ma-event-controller-connected is 1917 present for connectivity to a 1918 controller established event objects. 1920 ma-event-random-spread: The optional ma-event-random-spread 1921 adds a random delay defined in 1922 seconds to the event object. No 1923 random delay is added if ma-event- 1924 random-spread does not exist. 1926 ma-event-cycle-interval: The optional ma-event-cycle-interval 1927 defines the duration of the time 1928 interval in seconds that is used to 1929 calculate cycle numbers. No cycle 1930 number is calculated if ma-event- 1931 cycle-interval does not exist. 1933 3.11.2. Definition of ma-periodic-obj 1935 object { 1936 [datetime ma-periodic-start;] 1937 [datetime ma-periodic-end;] 1938 int ma-periodic-interval; 1939 } ma-periodic-obj; 1941 The ma-periodic-obj timing object has an optional start and an 1942 optional end time plus a periodic interval. Schedules using an ma- 1943 periodic-obj are started periodically between the start and end time. 1944 The ma-periodic-obj consists of the following elements: 1946 ma-periodic-start: The optional date and time at which 1947 Schedules using this object are first 1948 started. If not present it defaults to 1949 immediate. 1951 ma-periodic-end: The optional date and time at which 1952 Schedules using this object are last 1953 started. If not present it defaults to 1954 indefinite. 1956 ma-periodic-interval: The interval defines the time in seconds 1957 between two consecutive starts of tasks. 1959 3.11.3. Definition of ma-calendar-obj 1961 Calendar Timing supports the routine execution of Schedules at 1962 specific times and/or on specific dates. It can support more 1963 flexible timing than Periodic Timing since the execution of Schedules 1964 does not have to be uniformly spaced. For example a Calendar Timing 1965 could support the execution of a Measurement Task every hour between 1966 6pm and midnight on weekdays only. 1968 Calendar Timing is also required to perform measurements at 1969 meaningful times in relation to network usage (e.g., at peak times). 1970 If the optional timezone offset is not supplied then local system 1971 time is assumed. This is essential in some use cases to ensure 1972 consistent peak-time measurements as well as supporting MA devices 1973 that may be in an unknown timezone or roam between different 1974 timezones (but know their own timezone information such as through 1975 the mobile network). 1977 The calendar elements within the Calendar Timing do not have defaults 1978 in order to avoid accidental high-frequency execution of Tasks. If 1979 all possible values for an element are desired then the wildcard * is 1980 used. 1982 object { 1983 [datetime ma-calendar-start;] 1984 [datetime ma-calendar-end;] 1985 [string ma-calendar-months<0..*>;] 1986 [string ma-calendar-days-of-week<0..*>;] 1987 [string ma-calendar-days-of-month<0..*>;] 1988 [string ma-calendar-hours<0..*>;] 1989 [string ma-calendar-minutes<0..*>;] 1990 [string ma-calendar-seconds<0..*>;] 1991 [int ma-calendar-timezone-offset;] 1992 } ma-calendar-obj; 1994 ma-calendar-start: The optional date and time at which 1995 Schedules using this object are first 1996 started. If not present it defaults to 1997 immediate. 1999 ma-calendar-end: The optional date and time at which 2000 Schedules using this object are last 2001 started. If not present it defaults to 2002 indefinite. 2004 ma-calendar-months: The optional set of months (1-12) on 2005 which tasks scheduled using this object 2006 are started. The wildcard * means all 2007 months. If not present, it defaults to 2008 no months. 2010 ma-calendar-days-of-week: The optional set of days of a week 2011 ("Mon", "Tue", "Wed", "Thu", "Fri", 2012 "Sat", "Sun") on which tasks scheduled 2013 using this object are started. The 2014 wildcard * means all days of the week. 2015 If not present, it defaults to no days. 2017 ma-calendar-days-of-month: The optional set of days of a months 2018 (1-31) on which tasks scheduled using 2019 this object are started. The wildcard 2020 * means all days of a months. If not 2021 present, it defaults to no days. 2023 ma-calendar-hours: The optional set of hours (0-23) on 2024 which tasks scheduled using this object 2025 are started. The wildcard * means all 2026 hours of a day. If not present, it 2027 defaults to no hours. 2029 ma-calendar-minutes: The optional set of minutes (0-59) on 2030 which tasks scheduled using this object 2031 are started. The wildcard * means all 2032 minutes of an hour. If not present, it 2033 defaults to no hours. 2035 ma-calendar-seconds: The optional set of seconds (0-59) on 2036 which tasks scheduled using this object 2037 are started. The wildcard * means all 2038 seconds of an hour. If not present, it 2039 defaults to no seconds. 2041 ma-calendar-timezone-offset: The optional timezone offest in hours. 2042 If not present, it defaults to the 2043 system's local timezone. 2045 If a day of the month is specified that does not exist in the month 2046 (e.g., 29th of Feburary) then those values are ignored. 2048 3.11.4. Definition of ma-one-off-obj 2050 object { 2051 datetime ma-one-off-time; 2052 } ma-one-off-obj; 2054 The ma-one-off-obj timing object specifies a fixed point in time. 2055 Schedules using an ma-one-off-obj are started once at the specified 2056 date and time. The ma-one-off-obj consists of the following 2057 elements: 2059 ma-one-off-time: The date and time at which Schedules using 2060 this object are started. 2062 3.11.5. Definition of ma-immediate-obj 2064 object { 2065 // empty 2066 } ma-immediate-obj; 2068 The ma-immediate-obj event object has no further information 2069 elements. Schedules using an ma-immediate-obj are started as soon as 2070 possible. 2072 3.11.6. Definition of ma-startup-obj 2074 object { 2075 // empty 2076 } ma-startup-obj; 2078 The ma-startup-obj event object has no further information elements. 2079 Schedules or suppressions using an ma-startup-obj are started at MA 2080 initialization time. 2082 3.11.7. Definition of ma-controller-lost-obj 2084 object { 2085 // empty 2086 } ma-controller-lost-obj; 2088 The ma-controller-lost-obj event object has no further information 2089 elements. The ma-controller-lost-obj indicates that connectivity to 2090 the controller has been lost. This is determined by a timer started 2091 after each successful contact with a controller. When the timer 2092 reaches the controller-timeout (measured in seconds), an ma- 2093 controller-lost-obj event is generated. This event may be used to 2094 start a suppression. 2096 3.11.8. Definition of ma-controller-connected-obj 2098 object { 2099 // empty 2100 } ma-controller-connected-obj; 2102 The ma-controller-connected-obj event object has no further 2103 information elements. The ma-controller-connected-obj indicates that 2104 connectivity to the controller has been established again after it 2105 was lost. This event may be used to end a suppression. 2107 4. Example Execution 2109 The example execution has two event sources E1 and E2 and three 2110 schedules S1, S2, and S3. The schedule S3 is started by events of 2111 event source E2 while the schedules S1 and S2 are both started by 2112 events of the event source E1. The schedules S1 and S2 have two 2113 actions each and schedule S3 has a single action. The event source 2114 E2 has no randomization while the event source E1 has the 2115 randomization r. 2117 Figure 2 shows a possible timeline of an execution. The time T is 2118 progressing downwards. The dotted vertial line indicates progress of 2119 time while a dotted horizontal line indicates which schedule are 2120 triggered by an event. Tilded lines indicate data flowing from an 2121 action to another schedule. Actions within a schedule are named A1, 2122 A2, etc. 2124 E2 E1 T S1 S2 S3 2125 sequential parallel pipelined 2126 : 2127 e0 + 2128 : 2129 : 2130 e0+r + .......... + .......... ++ 2131 : | A1 A1 || A2 2132 : + |+ ~~~~~~~> 2133 : | A2 | 2134 : | + ~~~~~~~~> 2135 : + ~~~~~~~~~~~~~~~~~~~~~> 2136 : 2137 : 2138 e1 + 2139 : 2140 e1+r + .......... + .......... ++ 2141 : | A1 A1 || 2142 : | +|~~~~~~~> 2143 : | | A2 2144 : + +~~~~~~~> 2145 : | A2 2146 : + ~~~~~~~~~~~~~~~~~~~~> 2147 e0 + ................................... + 2148 : | A1 2149 e3 + | 2150 e3+r + .......... + .......... ++ | 2151 : | A1 A1 || A2 | 2152 : + ++ ~~~~~~> | 2153 : | A2 + 2154 : + ~~~~~~~~~~~~~~~~~~~~> 2155 V 2157 Figure 2: Example Execution 2159 Note that implementations must handle possible concurrency issues. 2160 In the example execution, action A1 of schedule S3 is consuming the 2161 data that has been forwarded to schedule S3 while additional data is 2162 arriving from action A2 of schedule S2. 2164 5. IANA Considerations 2166 This document makes no request of IANA. 2168 Note to RFC Editor: this section may be removed on publication as an 2169 RFC. 2171 6. Security Considerations 2173 This Information Model deals with information about the control and 2174 reporting of the Measurement Agent. There are broadly two security 2175 considerations for such an Information Model. Firstly the 2176 Information Model has to be sufficient to establish secure 2177 communication channels to the Controller and Collector such that 2178 other information can be sent and received securely. Additionally, 2179 any mechanisms that the Network Operator or other device 2180 administrator employs to pre-configure the MA must also be secure to 2181 protect unauthorized parties from modifying pre-configuration 2182 information. These mechanisms are important to ensure that the MA 2183 cannot be hijacked, for example to participate in a distributed 2184 denial of service attack. 2186 The second consideration is that no mandated information items should 2187 pose a risk to confidentiality or privacy given such secure 2188 communication channels. For this latter reason items such as the MA 2189 context and MA ID are left optional and can be excluded from some 2190 deployments. This would, for example, allow the MA to remain 2191 anonymous and for information about location or other context that 2192 might be used to identify or track the MA to be omitted or blurred. 2194 The Information Model should support wherever relevant, all the 2195 security and privacy requirements associated with the LMAP Framework. 2197 7. Acknowledgements 2199 The notation was inspired by the notation used in the ALTO protocol 2200 specification. 2202 Philip Eardley, Trevor Burbridge, Marcelo Bagnulo and Juergen 2203 Schoenwaelder worked in part on the Leone research project, which 2204 received funding from the European Union Seventh Framework Programme 2205 [FP7/2007-2013] under grant agreement number 317647. 2207 Juergen Schoenwaelder was partly funded by Flamingo, a Network of 2208 Excellence project (ICT-318488) supported by the European Commission 2209 under its Seventh Framework Programme. 2211 8. References 2213 8.1. Normative References 2215 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2216 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 2217 RFC2119, March 1997, 2218 . 2220 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 2221 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 2222 . 2224 [RFC7594] Eardley, P., Morton, A., Bagnulo, M., Burbridge, T., 2225 Aitken, P., and A. Akhter, "A Framework for Large-Scale 2226 Measurement of Broadband Performance (LMAP)", RFC 7594, 2227 DOI 10.17487/RFC7594, September 2015, 2228 . 2230 8.2. Informative References 2232 [I-D.ietf-ippm-metric-registry] 2233 Bagnulo, M., Claise, B., Eardley, P., Morton, A., and A. 2234 Akhter, "Registry for Performance Metrics", draft-ietf- 2235 ippm-metric-registry-07 (work in progress), July 2016. 2237 [I-D.ietf-lmap-yang] 2238 Schoenwaelder, J. and V. Bajpai, "A YANG Data Model for 2239 LMAP Measurement Agents", draft-ietf-lmap-yang-05 (work in 2240 progress), July 2016. 2242 [RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between 2243 Information Models and Data Models", RFC 3444, DOI 10 2244 .17487/RFC3444, January 2003, 2245 . 2247 [RFC7398] Bagnulo, M., Burbridge, T., Crawford, S., Eardley, P., and 2248 A. Morton, "A Reference Path and Measurement Points for 2249 Large-Scale Measurement of Broadband Performance", RFC 2250 7398, DOI 10.17487/RFC7398, February 2015, 2251 . 2253 Appendix A. Non-editorial Changes since -10 2255 o Rewrote the text concerning the well-known "channel" option name. 2257 o Added ma-report-result-event-time, ma-report-result-cycle-number, 2258 and ma-event-cycle-interval. 2260 o Added ma-capability-tags. 2262 o Added a new section showing an example execution. 2264 o Several clarifications and bug fixes. 2266 Appendix B. Non-editorial Changes since -09 2268 o Added ma-status-schedule-storage and ma-status-action-storage. 2270 o Removed suppress-by-default. 2272 o Moved ma-report-result-metrics of the ma-report-result-obj to ma- 2273 report-table-metrics of the ma-report-table-obj so that the 2274 relationship between metrics and result tables is clear. 2276 o Added ma-report-conflict-obj. 2278 o Added ma-report-result-status to ma-report-result-obj. 2280 o Several clarifications and bug fixes. 2282 Appendix C. Non-editorial Changes since -08 2284 o Refactored the ma-report-task-obj into the ma-report-result-obj. 2286 o Introduced the ma-report-table-obj so that a result can contain 2287 multiple tables. 2289 o Report schedule, action, and task name as part of the ma-report- 2290 result-obj. 2292 o Report conflicts per ma-report-result-obj and not per ma-report- 2293 row-obj. 2295 o Report the start/end time as part of the ma-report-result-obj. 2297 Appendix D. Non-editorial Changes since -07 2299 o Added ma-schedule-end and ma-schedule-duration. 2301 o Changed the granularity of scheduler timings to seconds. 2303 o Added ma-status-suppression-obj to report the status of 2304 suppressions as done in the YANG data model. 2306 o Added counters to schedule and action status objects to match the 2307 counters in the YANG data model. 2309 o Using tags to pass information such as a measurement cycle 2310 identifier to the collector. 2312 o Using suppression tags and glob-style matching to select schedules 2313 and actions to be suppressed. 2315 Appendix E. Non-editorial Changes since -06 2317 o The default execution mode is pipelined (LI12) 2319 o Added text to define which action consumes data in sequential, 2320 pipelines, and parallel execution mode (LI11) 2322 o Added ma-config-measurement-point, ma-report-measurement-point, 2323 and ma-config-report-measurement-point to configure and report the 2324 measurement point (LI10) 2326 o Turned ma-suppression-obj into a list that uses a start event and 2327 a stop event to define the start and end of suppression; this 2328 unifies the handling of suppression and loss of controller 2329 connectivity (LI09) 2331 o Added ma-controller-lost-obj and ma-controller-ok-obj event 2332 objects (LI09) 2334 o Added ma-status-schedule-obj to report the status of a schedule 2335 and refactored ma-task-status-obj into ma-status-action-obj to 2336 report the status of an action (LI07, LI08) 2338 o Introduced a common ma-metric-registry-obj that identifies a 2339 metric and a set of associated roles and added this object to 2340 expose metric capabilities and to support the configuration of 2341 metrics and to report the metrics used (LI06) 2343 o Introduced ma-capability-obj and ma-capability-task-obj to expose 2344 the capabilities of a measurement agent (LI05) 2346 o Use 'ordered list' or 'unordered set' instead of list, collection, 2347 etc. (LI02) 2349 o Clarification that Actions are part of a Schedule (LI03) 2351 o Deleted terms that are not strictly needed (LI04) 2353 Appendix F. Non-editorial Changes since -05 2355 o A task can now reference multiply registry entries. 2357 o Consistent usage of the term Action and Task. 2359 o Schedules are triggered by Events instead of Timings; Timings are 2360 just one of many possible event sources. 2362 o Actions feed into other Schedules (instead of Actions within other 2363 Schedules). 2365 o Removed the notion of multiple task outputs. 2367 o Support for sequential, parallel, and pipelined execution of 2368 Actions. 2370 Authors' Addresses 2372 Trevor Burbridge 2373 BT 2374 Adastral Park, Martlesham Heath 2375 Ipswich IP5 3RE 2376 United Kingdom 2378 Email: trevor.burbridge@bt.com 2380 Philip Eardley 2381 BT 2382 Adastral Park, Martlesham Heath 2383 Ipswich IP5 3RE 2384 United Kingdom 2386 Email: philip.eardley@bt.com 2388 Marcelo Bagnulo 2389 Universidad Carlos III de Madrid 2390 Av. Universidad 30 2391 Leganes, Madrid 28911 2392 Spain 2394 Email: marcelo@it.uc3m.es 2396 Juergen Schoenwaelder 2397 Jacobs University Bremen 2398 Campus Ring 1 2399 Bremen 28759 2400 Germany 2402 Email: j.schoenwaelder@jacobs-university.de