idnits 2.17.1 draft-ietf-lmap-information-model-13.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 702 has weird spacing: '...ion-obj ma-in...' == Line 891 has weird spacing: '...ask-obj ma-ca...' == Line 937 has weird spacing: '...ace-obj ma-...' == Line 939 has weird spacing: '...ion-obj ma-st...' == Line 973 has weird spacing: '...ion-obj ma-...' == (7 more instances...) -- The document date (November 17, 2016) is 2717 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: A later version (-24) exists of draft-ietf-ippm-metric-registry-07 == Outdated reference: A later version (-12) exists of draft-ietf-lmap-yang-05 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: May 21, 2017 M. Bagnulo 6 Universidad Carlos III de Madrid 7 J. Schoenwaelder 8 Jacobs University Bremen 9 November 17, 2016 11 Information Model for Large-Scale Measurement Platforms (LMAP) 12 draft-ietf-lmap-information-model-13 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 May 21, 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 5 67 3. LMAP Information Model . . . . . . . . . . . . . . . . . . . 5 68 3.1. Pre-Configuration Information . . . . . . . . . . . . . . 9 69 3.1.1. Definition of ma-preconfig-obj . . . . . . . . . . . 10 70 3.2. Configuration Information . . . . . . . . . . . . . . . . 10 71 3.2.1. Definition of ma-config-obj . . . . . . . . . . . . . 12 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 . . . . . . . . . . . . . . 19 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 . . . . . . . 25 84 3.5.7. Definition of ma-status-interface-obj . . . . . . . . 25 85 3.6. Reporting Information . . . . . . . . . . . . . . . . . . 26 86 3.6.1. Definition of ma-report-obj . . . . . . . . . . . . . 28 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 . . . . . . . . . . 31 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 . . . . . . . . . . . . 36 97 3.9. Common Objects: Task Configurations . . . . . . . . . . . 36 98 3.9.1. Definition of ma-task-obj . . . . . . . . . . . . . . 38 99 3.9.2. Definition of ma-option-obj . . . . . . . . . . . . . 38 100 3.10. Common Objects: Registry Information . . . . . . . . . . 39 101 3.10.1. Definition of ma-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 . . . . . . . . . . . 42 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 . . . . . . . . . . . 45 108 3.11.6. Definition of ma-startup-obj . . . . . . . . . . . . 45 109 3.11.7. Definition of ma-controller-lost-obj . . . . . . . . 45 110 3.11.8. Definition of ma-controller-connected-obj . . . . . 45 111 4. Example Execution . . . . . . . . . . . . . . . . . . . . . . 46 112 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47 113 6. Security Considerations . . . . . . . . . . . . . . . . . . . 48 114 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 48 115 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 49 116 8.1. Normative References . . . . . . . . . . . . . . . . . . 49 117 8.2. Informative References . . . . . . . . . . . . . . . . . 49 118 Appendix A. Change History . . . . . . . . . . . . . . . . . . . 49 119 A.1. Non-editorial changes since -13 . . . . . . . . . . . . . 50 120 A.2. Non-editorial changes since -12 . . . . . . . . . . . . . 50 121 A.3. Non-editorial changes since -11 . . . . . . . . . . . . . 50 122 A.4. Non-editorial changes since -10 . . . . . . . . . . . . . 50 123 A.5. Non-editorial changes since -09 . . . . . . . . . . . . . 50 124 A.6. Non-editorial changes since -08 . . . . . . . . . . . . . 51 125 A.7. Non-editorial changes since -07 . . . . . . . . . . . . . 51 126 A.8. Non-editorial changes since -06 . . . . . . . . . . . . . 51 127 A.9. Non-editorial changes since -05 . . . . . . . . . . . . . 52 128 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 52 130 1. Introduction 132 A large-scale measurement platform is a collection of components that 133 work in a coordinated fashion to perform measurements from a large 134 number of vantage points. The main components of a large-scale 135 measurement platform are the Measurement Agents (hereafter MAs), the 136 Controller(s) and the Collector(s). 138 The MAs are the elements actually performing the measurements. The 139 MAs are controlled by exactly one Controller at a time and the 140 Collectors gather the results generated by the MAs. In a nutshell, 141 the normal operation of a large-scale measurement platform starts 142 with the Controller instructing a set of one or more MAs to perform a 143 set of one or more Measurement Tasks at a certain point in time. The 144 MAs execute the instructions from a Controller, and once they have 145 done so, they report the results of the measurements to one or more 146 Collectors. The overall framework for a Large Measurement platform 147 as used in this document is described in detail in [RFC7594]. 149 A large-scale measurement platform involves basically three types of 150 protocols, namely, a Control protocol (or protocols) between a 151 Controller and the MAs, a Report protocol (or protocols) between the 152 MAs and the Collector(s) and several measurement protocols between 153 the MAs and Measurement Peers (MPs), used to actually perform the 154 measurements. In addition some information is required to be 155 configured on the MA prior to any communication with a Controller. 157 This document defines the information model for both Control and the 158 Report protocols along with pre-configuration information that is 159 required on the MA before communicating with the Controller, broadly 160 named as the LMAP Information Model. The measurement protocols are 161 out of the scope of this document. 163 As defined in [RFC3444], the LMAP Information Model defines the 164 concepts involved in a large-scale measurement platform at a high 165 level of abstraction, independent of any specific implementation or 166 actual protocol used to exchange the information. It is expected 167 that the proposed information model can be used with different 168 protocols in different measurement platform architectures and across 169 different types of MA devices (e.g., home gateway, smartphone, PC, 170 router). A YANG data model implementing the information model can be 171 found in [I-D.ietf-lmap-yang]. 173 The definition of an Information Model serves a number of purposes: 175 1. To guide the standardisation of one or more Control and Report 176 protocols and data models 178 2. To enable high-level inter-operability between different Control 179 and Report protocols by facilitating translation between their 180 respective data models such that a Controller could instruct sub- 181 populations of MAs using different protocols 183 3. To form agreement of what information needs to be held by an MA 184 and passed over the Control and Report interfaces and support the 185 functionality described in the LMAP framework 187 4. To enable existing protocols and data models to be assessed for 188 their suitability as part of a large-scale measurement system 190 2. Notation 192 This document uses a programming language-like notation to define the 193 properties of the objects of the information model. An optional 194 property is enclosed by square brackets, [ ], and a list property is 195 indicated by two numbers in angle brackets, , where m indicates 196 the minimal number of values, and n is the maximum. The symbol * for 197 n means no upper bound. 199 3. LMAP Information Model 201 The information described herein relates to the information stored, 202 received or transmitted by a Measurement Agent as described within 203 the LMAP framework [RFC7594]. As such, some subsets of this 204 information model are applicable to the measurement Controller, 205 Collector and any device management system that pre-configures the 206 Measurement Agent. The information described in these models will be 207 transmitted by protocols using interfaces between the Measurement 208 Agent and such systems according to a Data Model. 210 For clarity the information model is divided into six sections: 212 1. Pre-Configuration Information. Information pre-configured on the 213 Measurement Agent prior to any communication with other 214 components of the LMAP architecture (i.e., the Controller, 215 Collector and Measurement Peers), specifically detailing how to 216 communicate with a Controller and whether the device is enabled 217 to participate as an MA. 219 2. Configuration Information. Update of the pre-configuration 220 information during the registration of the MA or subsequent 221 communication with the Controller, along with the configuration 222 of further parameters about the MA (rather than the Measurement 223 Tasks it should perform) that were not mandatory for the initial 224 communication between the MA and a Controller. 226 3. Instruction Information. Information that is received by the MA 227 from the Controller pertaining to the Measurement Tasks that 228 should be executed. This includes the task execution Schedules 229 (other than the Controller communication Schedule supplied as 230 (pre)configuration information) and related information such as 231 the Task Configuration, communication Channels to Collectors and 232 schedule Event and Timing information. It also includes Task 233 Suppression information that is used to over-ride normal Task 234 execution. 236 4. Logging Information. Information transmitted from the MA to the 237 Controller detailing the results of any configuration operations 238 along with error and status information from the operation of the 239 MA. 241 5. Capability and Status Information. Information on the general 242 status and capabilities of the MA. For example, the set of 243 measurements that are supported on the device. 245 6. Reporting Information. Information transmitted from the MA to 246 one or more Collectors including measurement results and the 247 context in which they were conducted. 249 In addition the MA may hold further information not described herein, 250 and which may be optionally transferred to or from other systems 251 including the Controller and Collector. One example of information 252 in this category is subscriber or line information that may be 253 extracted by a task and reported by the MA in the reporting 254 communication to a Collector. 256 It should also be noted that the MA may be in communication with 257 other management systems which may be responsible for configuring and 258 retrieving information from the MA device. Such systems, where 259 available, can perform an important role in transferring the pre- 260 configuration information to the MA or enabling/disabling the 261 measurement functionality of the MA. 263 The Information Model is divided into sub-sections for a number of 264 reasons. Firstly the grouping of information facilitates reader 265 understanding. Secondly, the particular groupings chosen are 266 expected to map to different protocols or different transmissions 267 within those protocols. 269 The granularity of data transmitted in each operation of the Control 270 and Report Protocols is not dictated by the Information Model. For 271 example, the Instruction object may be delivered in a single 272 operation. Alternatively, Schedules and Task Configurations may be 273 separated or even each Schedule/Task Configuration may be delivered 274 individually. Similarly the Information Model does not dictate 275 whether data is read, write, or read/write. For example, some 276 Control Protocols may have the ability to read back Configuration and 277 Instruction information which have been previously set on the MA. 278 Lastly, while some protocols may simply overwrite information (for 279 example refreshing the entire Instruction Information), other 280 protocols may have the ability to update or delete selected items of 281 information. 283 The information in these six sections is captured by a number of 284 common information objects. These objects are also described later 285 in this document and comprise of: 287 1. Schedules. A set of Schedules tells the MA to do something. 288 Without a Schedule no Task (from a measurement to reporting or 289 communicating with the Controller) is ever executed. Schedules 290 are used within the Instruction to specify what tasks should be 291 performed, when, and how to direct their results. A Schedule is 292 also used within the pre-Configuration and Configuration 293 information in order to execute the Task or Tasks required to 294 communicate with the Controller. A specific Schedule can only be 295 active once. Attempts to start a Schedule while the same 296 Schedule is still running will fail. 298 2. Channels. A set of Channel objects are used to communicate with 299 a number of endpoints (i.e., the Controller and Collectors). 300 Each Channel object contains the information required for the 301 communication with a single endpoint such as the target location 302 and security details. 304 3. Task Configurations. A set of Task Configurations is used to 305 configure the Tasks that are run by the MA. This includes the 306 registry entries for the Task and any configuration parameters. 307 Task Configurations are referenced from a Schedule in order to 308 specify what Tasks the MA should execute. 310 4. Events. A set of Event objects that can be referenced from the 311 Schedules. Each Schedule always references exactly one Event 312 object that determines when the schedule is executed. An Event 313 object specifies either a singleton or series of events that 314 indicate when Tasks should be executed. A commonly used kind of 315 Event objects are Timing objects. 317 Figure 1 illustrates the structure in which these common information 318 objects are referenced. The references are achieved by each object 319 (Task Configuration, Event) being given a short textual name that is 320 used by other objects. The objects shown in parenthesis are part of 321 the internal object structure of a Schedule. Channels are not shown 322 in the diagram since they are only used as an option by selected Task 323 Configurations but are similarly referenced using a short text name. 325 Schedule 326 |-- triggered by --> Event 327 | 328 |-- executes --> Action 1 329 | |-- using --> Task Configuration 330 | | 331 | `-- feeding to --> Destination Schedule 332 : 333 : 334 `-- executes --> Action N 335 |-- using --> Task Configuration 336 | 337 `-- feeding to --> Destination Schedule 339 Figure 1: Relationship between Schedules, Events, Actions, Task 340 Configurations, and Destination Schedules 342 The primary function of an MA is to execute Schedules. Every Action 343 contained in a Schedule is defined as a Task. As such, these Actions 344 are configured through Task Configurations and executed according to 345 the Event object referenced by the Schedule in which they appear. 346 Note, however, that Actions can have Action specific parameters. 348 Tasks can implement a variety of different types of Actions. While 349 in terms of the Information Model, all Tasks have the same structure, 350 it can help conceptually to think of different Task categories: 352 1. Measurement Tasks measure some aspect of network performance or 353 traffic. They may also capture contextual information from the 354 MA device or network interfaces such as the device type or 355 interface speed. 357 2. Data Transfer Tasks support the communication with a Controller 358 and Collectors: 360 A. Reporting Tasks report the results of Measurement Tasks to 361 Collectors 363 B. Control Task(s) implement the Control Protocol and 364 communicate with the Controller. 366 3. Data Analysis Tasks can exist to analyse data from other 367 Measurement Tasks locally on the MA 369 4. Data Management Tasks may exist to clean-up, filter or compress 370 data on the MA such as Measurement Task results 372 Figure 1 indicates that Actions can produce data that is fed into 373 Destination Schedules. This can by used by Actions implementing 374 Measurement Tasks to feed measurement results to a Schedule that 375 triggers Actions implementing Reporting Tasks. Data fed to a 376 Destination Schedule is consumed by the first Action of the 377 Destination Schedule if the Destination Schedule is using sequential 378 or pipelined execution mode and it is consumed by all Actions of the 379 Destination Schedule if the Destination Schedule is using parallel 380 execution mode. 382 3.1. Pre-Configuration Information 384 This information is the minimal information that needs to be pre- 385 configured to the MA in order for it to successfully communicate with 386 a Controller during the registration process. Some of the Pre- 387 Configuration Information elements are repeated in the Configuration 388 Information in order to allow an LMAP Controller to update these 389 items. The pre-configuration information also contains some elements 390 that are not under the control of the LMAP framework (such as the 391 device identifier and device security credentials). 393 This Pre-Configuration Information needs to include a URL of the 394 initial Controller from where configuration information can be 395 communicated along with the security information required for the 396 communication including the certificate of the Controller (or the 397 certificate of the Certification Authority which was used to issue 398 the certificate for the Controller). All this is expressed as a 399 Channel. While multiple Channels may be provided in the Pre- 400 Configuration Information they must all be associated with a single 401 Controller (e.g., over different interfaces or network protocols). 403 Where the MA pulls information from the Controller, the Pre- 404 Configuration Information also needs to contain the timing of the 405 communication with the Controller as well as the nature of the 406 communication itself (such as the protocol and data to be 407 transferred). The timing is given as a Schedule that executes the 408 Task(s) responsible for communication with the Controller. It is 409 this Task (or Tasks) that implement the Control protocol between the 410 MA and the Controller and utilises the Channel information. The 411 Task(s) may take additional parameters in which case a Task 412 Configuration can also be included. 414 Even where information is pushed to the MA from the Controller 415 (rather than pulled by the MA), a Schedule still needs to be 416 supplied. In this case the Schedule will simply execute a Controller 417 listener task when the MA is started. A Channel is still required 418 for the MA to establish secure communication with the Controller. 420 It can be seen that these Channels, Schedules and Task Configurations 421 for the initial MA-Controller communication are no different in terms 422 of the Information Model to any other Channel, Schedule or Task 423 Configuration that might execute a Measurement Task or report the 424 measurement results (as described later). 426 The MA may be pre-configured with an MA ID, or may use a Device ID in 427 the first Controller contact before it is assigned an MA ID. The 428 Device ID may be a MAC address or some other device identifier 429 expressed as a URI. If the MA ID is not provided at this stage then 430 it must be provided by the Controller during Configuration. 432 3.1.1. Definition of ma-preconfig-obj 434 object { 435 [uuid ma-preconfig-agent-id;] 436 ma-task-obj ma-preconfig-control-tasks<1..*>; 437 ma-channel-obj ma-preconfig-control-channels<1..*>; 438 ma-schedule-obj ma-preconfig-control-schedules<1..*>; 439 [uri ma-preconfig-device-id;] 440 credentials ma-preconfig-credentials; 441 } ma-preconfig-obj; 443 The ma-preconfig-obj describes information that needs to be available 444 to the MA in order to bootstrap communication with a Controller. The 445 ma-preconfig-obj consists of the following elements: 447 ma-preconfig-agent-id: An optional uuid uniquely identifying 448 the measurement agent. 450 ma-preconfig-control-tasks: An unordered set of tasks objects. 452 ma-preconfig-control-channels: An unordered set of channel objects. 454 ma-preconfig-control-schedules: An unordered set of scheduling 455 objects. 457 ma-preconfig-device-id: An optional identifier for the 458 device. 460 ma-preconfig-credentials: The security credentials used by the 461 measurement agent. 463 3.2. Configuration Information 465 During registration or at any later point at which the MA contacts 466 the Controller (or vice-versa), the choice of Controller, details for 467 the timing of communication with the Controller or parameters for the 468 communication Task(s) can be changed (as captured by the Channels, 469 Schedules and Task Configurations objects). For example the pre- 470 configured Controller (specified as a Channel or Channels) may be 471 over-ridden with a specific Controller that is more appropriate to 472 the MA device type, location or characteristics of the network (e.g., 473 access technology type or broadband product). The initial 474 communication Schedule may be over-ridden with one more relevant to 475 routine communications between the MA and the Controller. 477 While some Control protocols may only use a single Schedule, other 478 protocols may use several Schedules (and related data transfer Tasks) 479 to update the Configuration Information, transfer the Instruction 480 Information, transfer Capability and Status Information and send 481 other information to the Controller such as log or error 482 notifications. Multiple Channels may be used to communicate with the 483 same Controller over multiple interfaces (e.g., to send logging 484 information over a different network). 486 In addition the MA will be given further items of information that 487 relate specifically to the MA rather than the measurements it is to 488 conduct or how to report results. The assignment of an ID to the MA 489 is mandatory. If the MA Agent ID was not optionally provided during 490 the pre-configuration then one must be provided by the Controller 491 during Configuration. Optionally a Group ID may also be given which 492 identifies a group of interest to which that MA belongs. For example 493 the group could represent an ISP, broadband product, technology, 494 market classification, geographic region, or a combination of 495 multiple such characteristics. Additional flags control whether the 496 MA ID or the Group ID are included in Reports. The reporting of a 497 Group ID without the MA ID allows the MA to remain anonymous, which 498 may be particularly useful to prevent tracking of mobile MA devices. 500 Optionally an MA can also be configured to stop executing any 501 Instruction Schedule if the Controller is unreachable. This can be 502 used as a fail-safe to stop Measurement and other Tasks being 503 conducted when there is doubt that the Instruction Information is 504 still valid. This is simply represented as a time window in seconds 505 since the last communication with the Controller after which an Event 506 is generated that can trigger the suspension of Instruction 507 Schedules. The appropriate value of the time window will depend on 508 the specified communication Schedule with the Controller and the 509 duration for which the system is willing to tolerate continued 510 operation with potentially stale Instruction Information. 512 While Pre-Configuration Information is persistent upon device reset 513 or power cycle, the persistency of the Configuration Information may 514 be device dependent. Some devices may revert back to their pre- 515 configuration state upon reboot or factory reset, while other devices 516 may store all Configuration and Instruction information in persistent 517 storage. A Controller can check whether an MA has the latest 518 Configuration and Instruction information by examining the Capability 519 and Status information for the MA. 521 3.2.1. Definition of ma-config-obj 523 object { 524 uuid ma-config-agent-id; 525 ma-task-obj ma-config-control-tasks<1..*>; 526 ma-channel-obj ma-config-control-channels<1..*>; 527 ma-schedule-obj ma-config-control-schedules<1..*>; 528 credentials ma-config-credentials; 529 [string ma-config-group-id;] 530 [string ma-config-measurement-point;] 531 [boolean ma-config-report-agent-id;] 532 [boolean ma-config-report-group-id;] 533 [boolean ma-config-report-measurement-point;] 534 [int ma-config-controller-timeout;] 535 } ma-config-obj; 537 The ma-config-obj consists of the following elements: 539 ma-config-agent-id: A uuid uniquely identifying the 540 measurement agent. 542 ma-config-control-tasks: An unordered set of task objects. 544 ma-config-control-channels: An unordered set of channel 545 objects. 547 ma-config-control-schedules: An unordered set of scheduling 548 objects. 550 ma-config-credentials: The security credentials used by 551 the measurement agent. 553 ma-config-group-id: An optional identifier of the 554 group of measurement agents this 555 measurement agent belongs to. 557 ma-config-measurement-point: An optional identifier for the 558 measurement point indicating 559 where the measurement agent is 560 located on a path (see [RFC7398] 561 for further details). 563 ma-config-report-agent-id: An optional flag indicating 564 whether the agent identifier (ma- 565 config-agent-id) is included in 566 reports. The default value is 567 true. 569 ma-config-report-group-id: An optional flag indicating 570 whether the group identifier (ma- 571 config-group-id) is included in 572 reports. The default value is 573 false. 575 ma-config-report-measurement-point: An optional flag indicating 576 whether the measurement point 577 (ma-config-measurement-point) 578 should be included in reports. 579 The default value is false. 581 ma-config-controller-timeout: A timer is started after each 582 successful contact with a 583 controller. When the timer 584 reaches the controller-timeout 585 (measured in seconds), an event 586 is raised indicating that 587 connectivity to the controller 588 has been lost (see ma-controller- 589 lost-obj). 591 3.3. Instruction Information 593 The Instruction information model has four sub-elements: 595 1. Instruction Task Configurations 597 2. Report Channels 599 3. Instruction Schedules 601 4. Suppression 603 The Instruction supports the execution of all Tasks on the MA except 604 those that deal with communication with the Controller (specified in 605 (pre-)configuration information). The Tasks are configured in 606 Instruction Task Configurations and included by reference in 607 Instruction Schedules that specify when to execute them. The results 608 can be communicated to other Schedules or a Task may implement a 609 Reporting Protocol and communicate results over Report Channels. 610 Suppression is used to temporarily stop the execution of new Tasks as 611 specified by the Instruction Schedules (and optionally to stop 612 ongoing Tasks). 614 A Task Configuration is used to configure the mandatory and optional 615 parameters of a Task. It also serves to instruct the MA about the 616 Task including the ability to resolve the Task to an executable and 617 specifying the schema for the Task parameters. 619 A Report Channel defines how to communicate with a single remote 620 system specified by a URL. A Report Channel is used to send results 621 to a single Collector but is no different in terms of the Information 622 Model to the Control Channel used to transfer information between the 623 MA and the Controller. Several Report Channels can be defined to 624 enable results to be split or duplicated across different 625 destinations. A single Channel can be used by multiple (reporting) 626 Task Configurations to transfer data to the same Collector. A single 627 Reporting Task Configuration can also be included in multiple 628 Schedules. E.g., a single Collector may receive data at three 629 different cycle rates, one Schedule reporting hourly, another 630 reporting daily and a third specifying that results should be sent 631 immediately for on-demand measurement tasks. Alternatively multiple 632 Report Channels can be used to send Measurement Task results to 633 different Collectors. The details of the Channel element is 634 described later as it is common to several objects. 636 Instruction Schedules specify which Actions to execute according to a 637 given triggering Event. An Action is a Task with additional specific 638 parameters. An Event can trigger the execution of a single Action or 639 it can trigger a repeated series of Actions. The Schedule also 640 specifies how to link Tasks output data to other Schedules. 642 Measurement Suppression information is used to over-ride the 643 Instruction Schedule and temporarily stop measurements or other Tasks 644 from running on the MA for a defined or indefinite period. While 645 conceptually measurements can be stopped by simply removing them from 646 the Measurement Schedule, splitting out separate information on 647 Measurement Suppression allows this information to be updated on the 648 MA on a different timing cycle or protocol implementation to the 649 Measurement Schedule. It is also considered that it will be easier 650 for a human operator to implement a temporary explicit suppression 651 rather than having to move to a reduced Schedule and then roll-back 652 at a later time. 654 It should be noted that control schedules and tasks cannot be 655 suppressed as evidenced by the lack of suppression information in the 656 Configuration. The control schedule must only reference tasks listed 657 as control tasks (i.e., within the Configuration information). 659 A single Suppression object is able to enable/disable a set of 660 Instruction Tasks that are tagged for suppression. This enabled fine 661 grained control on which Tasks are suppressed. Suppression of both 662 matching Actions and Measurement Schedules is supported. Support for 663 disabling specific Actions allows malfunctioning or mis-configured 664 Tasks or Actions that have an impact on a particular part of the 665 network infrastructure (e.g., a particular Measurement Peer) to be 666 targeted. Support for disabling specific Schedules allows for 667 particularly heavy cycles or sets of less essential Measurement Tasks 668 to be suppressed quickly and effectively. Note that Suppression has 669 no effect on either Controller Tasks or Controller Schedules. 671 Suppression stops new Tasks from executing. In addition, the 672 Suppression information also supports an additional Boolean that is 673 used to select whether on-going tasks are also to be terminated. 675 Unsuppression is achieved through either overwriting the Measurement 676 Suppression information (e.g., changing 'enabled' to False) or 677 through the use of an End time such that the Measurement Suppression 678 will no longer be in effect beyond this time. The datetime format 679 used for all elements in the information model (e.g., the suppression 680 start and end dates) MUST conform to RFC 3339 [RFC3339]. 682 The goal when defining these four different elements is to allow each 683 part of the information model to change without affecting the other 684 three elements. For example it is envisaged that the Report Channels 685 and the set of Task Configurations will be relatively static. The 686 Instruction Schedule, on the other hand, is likely to be more 687 dynamic, as the measurement panel and test frequency are changed for 688 various business goals. Another example is that measurements can be 689 suppressed with a Suppression command without removing the existing 690 Instruction Schedules that would continue to apply after the 691 Suppression expires or is removed. In terms of the Controller-MA 692 communication this can reduce the data overhead. It also encourages 693 the re-use of the same standard Task Configurations and Reporting 694 Channels to help ensure consistency and reduce errors. 696 3.3.1. Definition of ma-instruction-obj 698 object { 699 ma-task-obj ma-instruction-tasks<0..*>; 700 ma-channel-obj ma-instruction-channels<0..*>; 701 ma-schedule-obj ma-instruction-schedules<0..*>; 702 [ma-suppression-obj ma-instruction-suppressions<0..*>;] 703 } ma-instruction-obj; 705 An ma-instruction-obj consists of the following elements: 707 ma-instruction-tasks: A possibly empty unordered set of task 708 objects. 710 ma-instruction-channels: A possibly empty unordered set of 711 channel objects. 713 ma-instruction-schedules: A possibly empty unordered set of 714 schedule objects. 716 ma-instruction-suppressions: An optional possibly empty unordered 717 set of suppression objects. 719 3.3.2. Definition of ma-suppression-obj 721 object { 722 string ma-suppression-name; 723 [ma-event-obj ma-suppression-start;] 724 [ma-event-obj ma-suppression-end;] 725 [string ma-suppression-match<0..*>;] 726 [boolean ma-suppression-stop-running;] 727 } ma-suppression-obj; 729 The ma-suppression-obj controls the suppression of schedules or 730 actions and consists of the following elements: 732 ma-suppression-name: A name uniquely identifying a 733 suppression. 735 ma-suppression-start: The optional event indicating when 736 suppression starts. If not present, 737 the suppression starts immediately, 738 i.e., as if the value would be 739 'immediate'. 741 ma-suppression-end: The optional event indicating when 742 suppression ends. If not present, the 743 suppression does not have a defined 744 end, i.e., the suppression remains for 745 an indefinite period of time. 747 ma-suppression-match: An optional and possibly empty 748 unordered set of match patterns. The 749 suppression will apply to all schedules 750 (and their actions) that have a 751 matching value in their ma-schedule- 752 suppression-tags and all actions that 753 have a matching value in their ma- 754 action-suppression-tags. Pattern 755 matching is done using glob style 756 pattern (see below). 758 ma-suppression-stop-running: An optional boolean indicating whether 759 suppression will stop any running 760 matching schedules or actions. The 761 default value for this boolean is 762 false. 764 Glob style pattern matching is following POSIX.2 fnmatch() without 765 special treatment of file paths: 767 * matches a sequence of characters 768 ? matches a single character 769 [seq] matches any character in seq 770 [!seq] matches any character not in seq 772 A backslash followed by a character matches the following character. 773 In particular: 775 \* matches * 776 \? matches ? 777 \\ matches \ 779 A sequence seq may be a sequence of characters (e.g., [abc] or a 780 range of characters (e.g., [a-c]). 782 3.4. Logging Information 784 The MA may report on the success or failure of Configuration or 785 Instruction communications from the Controller. In addition further 786 operational logs may be produced during the operation of the MA and 787 updates to capabilities may also be reported. Reporting this 788 information is achieved in exactly the same manner as scheduling any 789 other Task. We make no distinction between a Measurement Task 790 conducting an active or passive network measurement and one which 791 solely retrieves static or dynamic information from the MA such as 792 capabilities or logging information. One or more logging tasks can 793 be programmed or configured to capture subsets of the Logging 794 Information. These logging tasks are then executed by Schedules 795 which also specify that the resultant data is to be transferred over 796 the Controller Channels. 798 The type of Logging Information will fall into three different 799 categories: 801 1. Success/failure/warning messages in response to information 802 updates from the Controller. Failure messages could be produced 803 due to some inability to receive or parse the Controller 804 communication, or if the MA is not able to act as instructed. 805 For example: 807 * "Measurement Schedules updated OK" 809 * "Unable to parse JSON" 811 * "Missing mandatory element: Measurement Timing" 813 * "'Start' does not conform to schema - expected datetime" 815 * "Date specified is in the past" 817 * "'Hour' must be in the range 1..24" 819 * "Schedule A refers to non-existent Measurement Task 820 Configuration" 822 * "Measurement Task Configuration X registry entry Y not found" 824 * "Updated Measurement Task Configurations do not include M used 825 by Measurement Schedule N" 827 2. Operational updates from the MA. For example: 829 * "Out of memory: cannot record result" 831 * "Collector 'collector.example.com' not responding" 833 * "Unexpected restart" 835 * "Suppression timeout" 837 * "Failed to execute Measurement Task Configuration H" 839 3. Status updates from the MA. For example: 841 * "Device interface added: eth3" 843 * "Supported measurements updated" 845 * "New IP address on eth0: xxx.xxx.xxx.xxx" 847 This Information Model document does not detail the precise format of 848 logging information since it is to a large extent protocol and MA 849 specific. However, some common information can be identified. 851 3.4.1. Definition of ma-log-obj 853 object { 854 uuid ma-log-agent-id; 855 datetime ma-log-event-time; 856 code ma-log-code; 857 string ma-log-description; 858 } ma-log-obj; 860 The ma-log-obj models the generic aspects of a logging object and 861 consists of the following elements: 863 ma-log-agent-id: A uuid uniquely identifying the measurement 864 agent. 866 ma-log-event-time: The date and time of the event reported in 867 the logging object. 869 ma-log-code: A machine readable code describing the 870 event. 872 ma-log-description: A human readable description of the event. 874 3.5. Capability and Status Information 876 The MA will hold Capability Information that can be retrieved by a 877 Controller. Capabilities include the device interface details 878 available to Measurement Tasks as well as the set of Measurement 879 Tasks/Roles (specified by registry entries) that are actually 880 installed or available on the MA. Status information includes the 881 times that operations were last performed such as contacting the 882 Controller or producing Reports. 884 3.5.1. Definition of ma-capability-obj 886 object { 887 string ma-capability-hardware; 888 string ma-capability-firmware; 889 string ma-capability-version; 890 [string ma-capability-tags<0..*>;] 891 [ma-capability-task-obj ma-capability-tasks<0..*>;] 892 } ma-capability-obj; 894 The ma-capability-obj provides information about the capabilities of 895 the measurement agent and consists of the following elements: 897 ma-capability-hardware: A description of the hardware of the device 898 the measurement agent is running on. 900 ma-capability-firmware: A description of the firmware of the device 901 the measurement agent is running on. 903 ma-capability-version: The version of the measurement agent. 905 ma-capability-tags: An optional unordered set of tags that 906 provide additional information about the 907 capabilities of the measurement agent. 909 ma-capability-tasks: An optional unordered set of capability 910 objects for each supported task. 912 3.5.2. Definition of ma-capability-task-obj 914 object { 915 string ma-capability-task-name; 916 ma-registry-obj ma-capability-task-functions<0..*>; 917 string ma-capability-task-version; 918 } ma-capability-task-obj; 920 The ma-capability-task-obj provides information about the capability 921 of a task and consists of the following elements: 923 ma-capability-task-name: A name uniquely identifying a task. 925 ma-capability-task-functions: A possibly empty unordered set of 926 registry entries identifying 927 functions this task implements. 929 ma-capability-task-version: The version of the measurement task. 931 3.5.3. Definition of ma-status-obj 933 object { 934 uuid ma-status-agent-id; 935 uri ma-status-device-id; 936 datetime ma-status-last-started; 937 ma-status-interface-obj ma-status-interfaces<0..*>; 938 [ma-status-schedule-obj ma-status-schedules<0..*>;] 939 [ma-status-suppression-obj ma-status-suppressions<0..*>;] 940 } ma-status-obj; 942 The ma-status-obj provides status information about the measurement 943 agent and consists of the following elements: 945 ma-status-agent-id: A uuid uniquely identifying the measurement 946 agent. 948 ma-status-device-id: A URI identifying the device. 950 ma-status-last-started: The date and time the measurement agent 951 last started. 953 ma-status-interfaces: An unordered set of network interfaces 954 available on the device. 956 ma-status-schedules: An optional unordered set of status objects 957 for each schedule. 959 ma-status-suppressions: An optional unordered set of status objects 960 for each suppression. 962 3.5.4. Definition of ma-status-schedule-obj 964 object { 965 string ma-status-schedule-name; 966 string ma-status-schedule-state; 967 int ma-status-schedule-storage; 968 counter ma-status-schedule-invocations; 969 counter ma-status-schedule-suppressions; 970 counter ma-status-schedule-overlaps; 971 counter ma-status-schedule-failures; 972 datetime ma-status-schedule-last-invocation; 973 [ma-status-action-obj ma-status-schedule-actions<0..*>;] 974 } ma-status-schedule-obj; 976 The ma-status-schedule-obj provides status information about the 977 status of a schedule and consists of the following elements: 979 ma-status-schedule-name: The name of the schedule this 980 status object refers to. 982 ma-status-schedule-state: The state of the schedule. The 983 value 'enabled' indicates that 984 the schedule is currently 985 enabled. The value 'suppressed' 986 indicates that the schedule is 987 currently suppressed. The value 988 'disabled' indicates that the 989 schedule is currently disabled. 990 The value 'running' indicates 991 that the schedule is currently 992 running. 994 ma-status-schedule-storage: The amount of secondary storage 995 (e.g., allocated in a file 996 system) holding temporary data 997 allocated to the schedule in 998 bytes. This object reports the 999 amount of allocated physical 1000 storage and not the storage used 1001 by logical data records. Data 1002 models should use a 64-bit 1003 integer type. 1005 ma-status-schedule-invocations Number of invocations of this 1006 schedule. This counter does not 1007 include suppressed invocations or 1008 invocations that were prevented 1009 due to an overlap with a previous 1010 invocation of this schedule. 1012 ma-status-schedule-suppressions Number of suppressed executions 1013 of this schedule. 1015 ma-status-schedule-overlaps Number of executions prevented 1016 due to overlaps with a previous 1017 invocation of this schedule. 1019 ma-status-schedule-failures Number of failed executions of 1020 this schedule. A failed 1021 execution is an execution where 1022 at least one action failed. 1024 ma-status-schedule-last-invocation: The date and time of the last 1025 invocation of this schedule. 1027 ma-status-schedule-actions: An optional ordered list of 1028 status objects for each action of 1029 the schedule. 1031 3.5.5. Definition of ma-status-action-obj 1032 object { 1033 string ma-status-action-name; 1034 string ma-status-action-state; 1035 int ma-status-action-storage; 1036 counter ma-status-action-invocations; 1037 counter ma-status-action-suppressions; 1038 counter ma-status-action-overlaps; 1039 counter ma-status-action-failures; 1040 datetime ma-status-action-last-invocation; 1041 datetime ma-status-action-last-completion; 1042 int ma-status-action-last-status; 1043 string ma-status-action-last-message; 1044 datetime ma-status-action-last-failed-completion; 1045 int ma-status-action-last-failed-status; 1046 string ma-status-action-last-failed-message; 1047 } ma-status-action-obj; 1049 The ma-status-action-obj provides status information about an action 1050 of a schedule and consists of the following elements: 1052 ma-status-action-name: The name of the action of a 1053 schedule this status object 1054 refers to. 1056 ma-status-action-state: The state of the action. 1057 The value 'enabled' 1058 indicates that the action is 1059 currently enabled. The 1060 value 'suppressed' indicates 1061 that the action is currently 1062 suppressed. The value 1063 'disabled' indicates that 1064 the action is currently 1065 disabled. The value 1066 'running' indicates that the 1067 action is currently running. 1069 ma-status-action-storage: The amount of secondary 1070 storage (e.g., allocated in 1071 a file system) holding 1072 temporary data allocated to 1073 the action in bytes. This 1074 object reports the amount of 1075 allocated physical storage 1076 and not the storage used by 1077 logical data records. Data 1078 models should use a 64-bit 1079 integer type. 1081 ma-status-action-invocations Number of invocations of 1082 this action. This counter 1083 does not include suppressed 1084 invocations or invocations 1085 that were prevented due to 1086 an overlap with a previous 1087 invocation of this action. 1089 ma-status-action-suppressions Number of suppressed 1090 executions of this action. 1092 ma-status-action-overlaps Number of executions 1093 prevented due to overlaps 1094 with a previous invocation 1095 of this action. 1097 ma-status-action-failures Number of failed executions 1098 of this action. 1100 ma-status-action-last-invocation: The date and time of the 1101 last invocation of this 1102 action. 1104 ma-status-action-last-completion: The date and time of the 1105 last completion of this 1106 action. 1108 ma-status-action-last-status: The status code returned by 1109 the last execution of this 1110 action. 1112 ma-status-action-last-message: The status message produced 1113 by the last execution of 1114 this action. 1116 ma-status-action-last-failed-completion: The date and time of the 1117 last failed completion of 1118 this action. 1120 ma-status-action-last-failed-status: The status code returned by 1121 the last failed execution of 1122 this action. 1124 ma-status-action-last-failed-message: The status message produced 1125 by the last failed execution 1126 of this action. 1128 3.5.6. Definition of ma-status-suppression-obj 1130 object { 1131 string ma-status-suppression-name; 1132 string ma-status-suppression-state; 1133 } ma-status-suppression-obj; 1135 The ma-status-suppression-obj provides status information about that 1136 status of a suppression and consists of the following elements: 1138 ma-status-suppression-name: The name of the suppression this status 1139 object refers to. 1141 ma-status-suppression-state: The state of the suppression. The 1142 value 'enabled' indicates that the 1143 suppression is currently enabled. The 1144 value 'active indicates that the 1145 suppression is currently active. The 1146 value 'disabled' indicates that the 1147 suppression is currently disabled. 1149 3.5.7. Definition of ma-status-interface-obj 1151 object { 1152 string ma-status-interface-name; 1153 string ma-status-interface-type; 1154 [int ma-status-interface-speed;] 1155 [string ma-status-interface-link-layer-address;] 1156 [ip-address ma-status-interface-ip-addresses<0..*>;] 1157 [ip-address ma-status-interface-gateways<0..*>;] 1158 [ip-address ma-status-interface-dns-servers<0..*>;] 1159 } ma-status-interface-obj; 1161 The ma-status-interface-obj provides status information about network 1162 interfaces and consists of the following elements: 1164 ma-status-interface-name: A name uniquely identifying a 1165 network interface. 1167 ma-status-interface-type: The type of the network 1168 interface. 1170 ma-status-interface-speed: An optional indication of the 1171 speed of the interface 1172 (measured in bits-per- 1173 second). 1175 ma-status-interface-link-layer-address: An optional link-layer 1176 address of the interface. 1178 ma-status-interface-ip-addresses: An optional ordered list of 1179 IP addresses assigned to the 1180 interface. 1182 ma-status-interface-gateways: An optional ordered list of 1183 gateways assigned to the 1184 interface. 1186 ma-status-interface-dns-servers: An optional ordered list of 1187 DNS servers assigned to the 1188 interface. 1190 3.6. Reporting Information 1192 At a point in time specified by a Schedule, the MA will execute tasks 1193 that communicate a set of measurement results to the Collector. 1194 These Reporting Tasks will be configured to transmit task results 1195 over a specified Report Channel to a Collector. 1197 It should be noted that the output from Tasks does not need to be 1198 sent to communication Channels. It can alternatively, or 1199 additionally, be sent to other Tasks on the MA. This facilitates 1200 using a first Measurement Task to control the operation of a later 1201 Measurement Task (such as first probing available line speed and then 1202 adjusting the operation of a video testing measurement) and also to 1203 allow local processing of data to output alarms (e.g., when 1204 performance drops from earlier levels). Of course, subsequent Tasks 1205 also include Tasks that implement the reporting protocol(s) and 1206 transfer data to one or more Collector(s). 1208 The Report generated by a Reporting Task is structured hierarchically 1209 to avoid repetition of report header and Measurement Task 1210 Configuration information. The report starts with the timestamp of 1211 the report generation on the MA and details about the MA including 1212 the optional Measurement Agent ID and Group ID (controlled by the 1213 Configuration Information). 1215 Much of the report Information is optional and will depend on the 1216 implementation of the Reporting Task and any parameters defined in 1217 the Task Configuration for the Reporting Task. For example some 1218 Reporting Tasks may choose not to include the Measurement Task 1219 Configuration or Action parameters, while others may do so dependent 1220 on the Controller setting a configurable parameter in the Task 1221 Configuration. 1223 It is possible for a Reporting Task to send just the Report header 1224 (datetime and optional agent ID and/or Group ID) if no measurement 1225 data is available. Whether to send such empty reports again is 1226 dependent on the implementation of the Reporting Task and potential 1227 Task Configuration parameter. 1229 The handling of measurement data on the MA before generating a Report 1230 and transfer from the MA to the Collector is dependent on the 1231 implementation of the device, MA and/or scheduled Tasks and not 1232 defined by the LMAP standards. Such decisions may include limits to 1233 the measurement data storage and what to do when such available 1234 storage becomes depleted. It is generally suggested that 1235 implementations running out of storage stop executing new measurement 1236 tasks and retain old measurement data. 1238 No context information, such as line speed or broadband product are 1239 included within the report header information as this data is 1240 reported by individual tasks at the time they execute. Either a 1241 Measurement Task can report contextual parameters that are relevant 1242 to that particular measurement, or specific tasks can be used to 1243 gather a set of contextual and environmental data at certain times 1244 independent of the reporting schedule. 1246 After the report header information the results are reported grouped 1247 according to different Measurement Task Configurations. Each Task 1248 section optionally starts with replicating the Measurement Task 1249 Configuration information before the result headers (titles for data 1250 columns) and the result data rows. The Options reported are those 1251 used for the scheduled execution of the Measurement Task and 1252 therefore include the Options specified in the Task Configuration as 1253 well as additional Options specified in the Action. The Action 1254 Options are appended to the Task Configuration Options in exactly the 1255 same order as they were provided to the Task during execution. 1257 The result row data includes a time for the start of the measurement 1258 and optionally an end time where the duration also needs to be 1259 considered in the data analysis. 1261 Some Measurement Tasks may optionally include an indication of the 1262 cross-traffic although the definition of cross-traffic is left up to 1263 each individual Measurement Task. Some Measurement Tasks may also 1264 output other environmental measures in addition to cross-traffic such 1265 as CPU utlilisation or interface speed. 1267 Where the Configuration and Instruction information represent 1268 information transmitted via the Control Protocol, the Report 1269 represents the information that is transmitted via the Report 1270 Protocol. It is constructed at the time of sending a report and 1271 represents the inherent structure of the information that is sent to 1272 the Collector. 1274 3.6.1. Definition of ma-report-obj 1276 object { 1277 datetime ma-report-date; 1278 [uuid ma-report-agent-id;] 1279 [string ma-report-group-id;] 1280 [string ma-report-measurement-point;] 1281 [ma-report-result-obj ma-report-results<0..*>;] 1282 } ma-report-obj; 1284 The ma-report-obj provides the meta-data of a single report and 1285 consists of the following elements: 1287 ma-report-date: The date and time when the report was 1288 sent to a collector. 1290 ma-report-agent-id: An optional uuid uniquely identifying 1291 the measurement agent. 1293 ma-report-group-id: An optional identifier of the group of 1294 measurement agents this measurement 1295 agent belongs to. 1297 ma-report-measurement-point: An optional identifier for the 1298 measurement point indicating where the 1299 measurement agent is located on a path 1300 (see [RFC7398] for further details). 1302 ma-report-results: An optional and possibly empty 1303 unordered set of result objects. 1305 3.6.2. Definition of ma-report-result-obj 1306 object { 1307 string ma-report-result-schedule-name; 1308 string ma-report-result-action-name; 1309 string ma-report-result-task-name; 1310 [ma-option-obj ma-report-result-options<0..*>;] 1311 [string ma-report-result-tags<0..*>;] 1312 datetime ma-report-result-event-time; 1313 datetime ma-report-result-start-time; 1314 [datetime ma-report-result-end-time;] 1315 [string ma-report-result-cycle-number;] 1316 int ma-report-result-status; 1317 [ma-report-conflict-obj ma-report-result-conflicts<0..*>;] 1318 [ma-report-table-obj ma-report-result-tables<0..*>;] 1319 } ma-report-result-obj; 1321 The ma-report-result-obj provides the meta-data of a result report of 1322 a single executed action. It consists of the following elements: 1324 ma-report-result-schedule-name: The name of the schedule that 1325 produced the result. 1327 ma-report-result-action-name: The name of the action in the 1328 schedule that produced the result. 1330 ma-report-result-task-name: The name of the task that produced 1331 the result. 1333 ma-report-result-options: An optional ordered joined list of 1334 options provided by the task object 1335 and the action object when the action 1336 was started. 1338 ma-report-result-tags: An optional unordered set of tags. 1339 This is the joined set of tags 1340 provided by the task object and the 1341 action object and schedule object 1342 when the action was started. 1344 ma-report-result-event-time: The date and time of the event that 1345 triggered the schedule of the action 1346 that produced the reported result 1347 values. The date and time does not 1348 include any added randomization. 1350 ma-report-result-start-time: The date and time of the start of the 1351 action that produced the reported 1352 result values. 1354 ma-report-result-end-time: An optional date and time indicating 1355 when the action finished. 1357 ma-report-result-cycle-number: An optional cycle number derived from 1358 ma-report-result-event-time. It is 1359 the time closest to ma-report-result- 1360 event-time that is a multiple of the 1361 ma-event-cycle-interval of the event 1362 that triggered the execution of the 1363 schedule. The value is only present 1364 in an ma-report-result-obj if the 1365 event that triggered the execution of 1366 the schedule has a defined ma-event- 1367 cycle-interval. The cycle number is 1368 represented in the format 1369 YYYYMMDD.HHMMSS where YYYY represents 1370 the year, MM the month (1..12), DD 1371 the day of the months (01..31), HH 1372 the hour (00..23), MM the minute 1373 (00..59), and SS the second (00..59). 1375 ma-report-result-status: The status code returned by the 1376 execution of the action. 1378 ma-report-result-conflicts: A possibly empty set of conflict 1379 actions that might have impacted the 1380 measurement results being reported. 1382 ma-report-result-tables: An optional and possibly empty 1383 unordered set of result tables. 1385 3.6.3. Definition of ma-report-conflict-obj 1387 object { 1388 string ma-report-conflict-schedule-name; 1389 string ma-report-conflict-action-name; 1390 string ma-report-conflict-task-name; 1391 } ma-report-conflict-obj; 1393 The ma-report-conflict-obj provides the information about conflicting 1394 action that might have impacted the measurement results. It consists 1395 of the following elements: 1397 ma-report-result-schedule-name: The name of the schedule that may 1398 have impacted the result. 1400 ma-report-result-action-name: The name of the action in the 1401 schedule that may have impacted the 1402 result. 1404 ma-report-result-task-name: The name of the task that may have 1405 impacted the result. 1407 3.6.4. Definition of ma-report-table-obj 1409 object { 1410 [ma-registry-obj ma-report-table-functions<0..*>;] 1411 [string] ma-report-table-column-labels<0..*>;] 1412 [ma-report-row-obj ma-report-table-rows<0..*>;] 1413 } ma-report-table-obj; 1415 The ma-report-table-obj represents a result table and consists of the 1416 following elements: 1418 ma-report-table-functions: An optional and possibly empty 1419 unordered set of registry entries 1420 identifying the functions for which 1421 results that are reported. 1423 ma-report-table-column-labels: An optional and possibly empty 1424 ordered list of column labels. 1426 ma-report-table-rows: A possibly empty ordered list of 1427 result rows. 1429 3.6.5. Definition of ma-report-row-obj 1431 object { 1432 data ma-report-row-values<0..*>; 1433 } ma-report-row-obj; 1435 The ma-report-row-obj represents a result row and consists of the 1436 following elements: 1438 ma-report-row-values: A possibly empty ordered list of result 1439 values. When present, it contains an 1440 ordered list of values that align to the 1441 set of column labels for the report. 1443 3.7. Common Objects: Schedules 1445 A Schedule specifies the execution of a single or repeated series of 1446 Actions. An Action is a Task with additional specific parameters. 1447 Each Schedule contains basically two elements: an ordered list of 1448 Actions to be executed and an Event object triggering the execution 1449 of the Schedule. The Schedule states what Actions to run (with what 1450 configuration) and when to run the Actions. A Schedule may 1451 optionally have an Event that stops the execution of the Schedule or 1452 a maximum duration after which a schedule is stopped. 1454 Multiple Actions contained as an ordered list of a single Measurement 1455 Schedule will be executed according to the execution mode of the 1456 Schedule. In sequential mode, Actions will be executed sequentially 1457 and in parallel mode, all Actions will be executed concurrently. In 1458 pipelined mode, data produced by one Action is passed to the 1459 subsequent Action. Actions contained in different Schedules execute 1460 in parallel with such conflicts being reported in the Reporting 1461 Information where necessary. If two or more Schedules have the same 1462 start time, then the two will execute in parallel. There is no 1463 mechanism to prioritise one schedule over another or to mutex 1464 scheduled tasks. 1466 As well as specifying which Actions to execute, the Schedule also 1467 specifies how to link the data outputs from each Action to other 1468 Schedules. Specifying this within the Schedule allows the highest 1469 level of flexibility since it is even possible to send the output 1470 from different executions of the same Task Configuration to different 1471 destinations. A single Task producing multiple different outputs is 1472 expected to properly tag the different result. An Action receiving 1473 the output can then filter the results based on the tag if necessary. 1474 For example, a Measurement Task might report routine results to a 1475 data Reporting Task in a Schedule that communicates hourly via the 1476 Broadband PPP interface, but also outputs emergency conditions via an 1477 alarm Reporting Task in a different Schedule communicating 1478 immediately over a GPRS channel. Note that task-to-task data 1479 transfer is always specified in association with the scheduled 1480 execution of the sending task - there is no need for a corresponding 1481 input specification for the receiving task. While it is likely that 1482 an MA implementation will use a queue mechanism between the Schedules 1483 or Actions, this Information Model does not mandate or define a 1484 queue. The Information Model, however, reports the storage allocated 1485 to Schedules and Actions so that storage usage can be monitored. 1486 Furthermore, it is recommended that MA implementations by default 1487 retain old data and stop the execution of new measurement tasks if 1488 the MA runs out of storage capacity. 1490 When specifying the task to execute within the Schedule, i.e., 1491 creating an Action, it is possible to add to the Action option 1492 parameters. This allows the Task Configuration to determine the 1493 common characteristics of a Task, while selected parameters (e.g., 1494 the test target URL) are defined within as option parameters of the 1495 Action in the schedule. A single Tasks Configuration can even be 1496 used multiple times in the same schedule with different additional 1497 parameters. This allows for efficiency in creating and transferring 1498 the Instruction. Note that the semantics of what happens if an 1499 option is defined multiple times (either in the Task Configuration, 1500 Action or in both) is not standardised and will depend upon the Task. 1501 For example, some tasks may legitimately take multiple values for a 1502 single parameter. 1504 Where Options are specified in both the Action and the Task 1505 Configuration, the Action Options are appended to those specified in 1506 the Task Configuration. 1508 Example: An Action of a Schedule references a single Measurement 1509 Task Configuration for measuring UDP latency. It specifies that 1510 results are to be sent to a Schedule with a Reporting Action. 1511 This Reporting Task of the Reporting Action is executed by a 1512 separate Schedule that specifies that it should run hourly at 5 1513 minutes past the hour. When run this Reporting Action takes the 1514 data generated by the UDP latency Measurement Task as well as any 1515 other data to be included in the hourly report and transfers it to 1516 the Collector over the Report Channel specified within its own 1517 Schedule. 1519 Schedules and Actions may optionally also be given tags that are 1520 included in result reports sent to a Collector. In addition, 1521 schedules can be given suppression tags that may be used to select 1522 Schedules and Actions for suppression. 1524 3.7.1. Definition of ma-schedule-obj 1526 object { 1527 string ma-schedule-name; 1528 ma-event-obj ma-schedule-start; 1529 [ma-event-obj ma-schedule-end;] 1530 [int ma-schedule-duration;] 1531 ma-action-obj ma-schedule-actions<0..*>; 1532 string ma-schedule-execution-mode; 1533 [string ma-schedule-tags<0..*>;] 1534 [string ma-schedule-suppression-tags<0..*>;] 1535 } ma-schedule-obj; 1537 The ma-schedule-obj is the main scheduling object. It consists of 1538 the following elements: 1540 ma-schedule-name: A name uniquely identifying a 1541 scheduling object. 1543 ma-schedule-start: An event object indicating when the 1544 schedule starts. 1546 ma-schedule-end: An optional event object controlling 1547 the forceful termination of scheduled 1548 actions. When the event occurs, all 1549 actions of the schedule will be forced 1550 to terminate gracefully. 1552 ma-schedule-duration: An optional duration in seconds for the 1553 schedule. All actions of the schedule 1554 will be forced to terminate gracefully 1555 after the duration number of seconds 1556 past the start of the schedule. 1558 ma-schedule-actions: A possibly empty ordered list of 1559 actions to invoke when the schedule 1560 starts. 1562 ma-schedule-execution-mode: Indicates whether the actions should be 1563 executed sequentially, in parallel, or 1564 in a pipelined mode (where data 1565 produced by one action is passed to the 1566 subsequent action). The default 1567 execution mode is pipelined. 1569 ma-schedule-tags: An optional unordered set of tags that 1570 are reported together with the 1571 measurement results to a collector. 1573 ma-schedule-suppression-tags: An optional unordered set of 1574 suppression tags that are used to 1575 select schedules to be suppressed. 1577 3.7.2. Definition of ma-action-obj 1579 object { 1580 string ma-action-name; 1581 string ma-action-config-task-name; 1582 [ma-option-obj ma-action-task-options<0..*>;] 1583 [string ma-action-destinations<0..*>;] 1584 [string ma-action-tags<0..*>;] 1585 [string ma-action-suppression-tags<0..*>;] 1586 } ma-action-obj; 1588 The ma-action-obj models a task together with its schedule specific 1589 task options and destination schedules. It consists of the following 1590 elements: 1592 ma-action-name: A name uniquely identifying an action 1593 of a scheduling object. 1595 ma-action-config-task-name: A name identifying the configured task 1596 to be invoked by the action. 1598 ma-action-task-options: An optional and possibly empty ordered 1599 list of options (name-value pairs) that 1600 are passed to the task by appending 1601 them to the options configured for the 1602 task object. 1604 ma-action-destinations: An optional and possibly empty 1605 unordered set of names of destination 1606 schedules that consume output produced 1607 by this action. 1609 ma-action-tags: An optional unordered set of tags that 1610 are reported together with the 1611 measurement results to a collector. 1613 ma-action-suppression-tags: An optional unordered set of 1614 suppression tags that are used to 1615 select actions to be suppressed. 1617 3.8. Common Objects: Channels 1619 A Channel defines a bi-directional communication channel between the 1620 MA and a Controller or Collector. Multiple Channels can be defined 1621 to enable results to be split or duplicated across different 1622 Collectors. 1624 Each Channel contains the details of the remote endpoint (including 1625 location and security credential information such as the 1626 certificate). The timing of when to communicate over a Channel is 1627 specified by the Schedule which executes the corresponding Control or 1628 Reporting Task. The certificate can be the digital certificate 1629 associated to the FQDN in the URL or it can be the certificate of the 1630 Certification Authority that was used to issue the certificate for 1631 the FQDN (Fully Qualified Domain Name) of the target URL (which will 1632 be retrieved later on using a communication protocol such as TLS). 1633 In order to establish a secure channel, the MA will use it's own 1634 security credentials (in the Configuration Information) and the given 1635 credentials for the individual Channel end-point. 1637 As with the Task Configurations, each Channel is also given a text 1638 name by which it can be referenced as a Task Option. 1640 Although the same in terms of information, Channels used for 1641 communication with the Controller are referred to as Control Channels 1642 whereas Channels to Collectors are referred to as Report Channels. 1643 Hence Control Channels will be referenced from Control Tasks executed 1644 by a Control Schedule, whereas Report Channels will be referenced 1645 from within Reporting Tasks executed by an Instruction Schedule. 1647 Multiple interfaces are also supported. For example the Reporting 1648 Task could be configured to send some results over GPRS. This is 1649 especially useful when such results indicate the loss of connectivity 1650 on a different network interface. 1652 Example: A Channel used for reporting results may specify that 1653 results are to be sent to the URL (https://collector.example.org/ 1654 report/), using the appropriate digital certificate to establish a 1655 secure channel. 1657 3.8.1. Definition of ma-channel-obj 1659 object { 1660 string ma-channel-name; 1661 url ma-channel-target; 1662 credentials ma-channel-credentials; 1663 [string ma-channel-interface-name;] 1664 } ma-channel-obj; 1666 The ma-channel-obj consists of the following elements: 1668 ma-channel-name: A unique name identifying the channel 1669 object. 1671 ma-channel-target: A URL identifying the target channel 1672 endpoint. 1674 ma-channel-credentials: The security credentials needed to 1675 establish a secure channel. 1677 ma-channel-interface-name: An optional name of the network interface 1678 to be used. If not present, the IP 1679 protocol stack will select a suitable 1680 interface. 1682 3.9. Common Objects: Task Configurations 1684 Conceptually each Task Configuration defines the parameters of a Task 1685 that the Measurement Agent (MA) may perform at some point in time. 1686 It does not by itself actually instruct the MA to perform them at any 1687 particular time (this is done by a Schedule). Tasks can be 1688 Measurement Tasks (i.e., those Tasks actually performing some type of 1689 passive or active measurement) or any other scheduled activity 1690 performed by the MA such as transferring information to or from the 1691 Controller and Collectors. Other examples of Tasks may include data 1692 manipulation or processing Tasks conducted on the MA. 1694 A Measurement Task Configuration is the same in information terms to 1695 any other Task Configuration. Both measurement and non-measurement 1696 Tasks have registry entries to enable the MA to uniquely identify the 1697 Task it should execute and retrieve the schema for any parameters 1698 that may be passed to the Task. Registry entries are specified as a 1699 URI and can therefore be used to identify the Task within a namespace 1700 or point to a web or local file location for the Task information. 1701 As mentioned previously, these URIs may be used to identify the 1702 Measurement Task in a public namespace 1703 [I-D.ietf-ippm-metric-registry]. 1705 Example: A Measurement Task Configuration may configure a single 1706 Measurement Task for measuring UDP latency. The Measurement Task 1707 Configuration could define the destination port and address for 1708 the measurement as well as the duration, internal packet timing 1709 strategy and other parameters (for example a stream for one hour 1710 and sending one packet every 500 ms). It may also define the 1711 output type and possible parameters (for example the output type 1712 can be the 95th percentile mean) where the measurement task 1713 accepts such parameters. It does not define when the task starts 1714 (this is defined by the Schedule element), so it does not by 1715 itself instruct the MA to actually perform this Measurement Task. 1717 The Task Configuration will include a local short name for reference 1718 by a Schedule. Task Configurations may also refer to registry 1719 entries as described above. In addition the Task can be configured 1720 through a set of configuration Options. The nature and number of 1721 these Options will depend upon the Task. These options are expressed 1722 as name-value pairs although the 'value' may be a structured object 1723 instead of a simple string or numeric value. The implementation of 1724 these name-value pairs will vary between data models. 1726 An Option that must be present for Reporting Tasks is the Channel 1727 reference specifying how to communicate with a Collector. This is 1728 included in the task options and will have a value that matches a 1729 channel name that has been defined in the Instruction. Similarly 1730 Control Tasks will have a similar option with the value set to a 1731 specified Control Channel. 1733 A Reporting Task might also have a flag parameter to indicate whether 1734 to send a report without measurement results if there is no 1735 measurement result data pending to be transferred to the Collector. 1737 In addition many tasks will also take as a parameter which interface 1738 to operate over. 1740 In addition the Task Configuration may optionally also be given tags 1741 that can carry a Measurement Cycle ID. The purpose of this ID is to 1742 easily identify a set of measurement results that have been produced 1743 by Measurement Tasks with comparable Options. This ID could be 1744 manually incremented or otherwise changed when an Option change is 1745 implemented which could mean that two sets of results should not be 1746 directly compared. 1748 3.9.1. Definition of ma-task-obj 1750 object { 1751 string ma-task-name; 1752 ma-registry-obj ma-task-functions<0..*>; 1753 [ma-option-obj ma-task-options<0..*>;] 1754 [string ma-task-tags<0..*>;] 1755 } ma-task-obj; 1757 The ma-task-obj defines a configured task that can be invoked as part 1758 of an action. A configured task can be referenced by its name and it 1759 contains a set of URIs to link to registry entries or a local 1760 specification of the task. Options allow the configuration of task 1761 parameters (in the form of name-value pairs). The ma-task-obj 1762 consists of the following elements: 1764 ma-task-name: A name uniquely identifying a configured 1765 task object. 1767 ma-task-functions: A possibly empty unordered set of registry 1768 entries identifying the functions of the 1769 configured task. 1771 ma-task-options: An optional and possibly empty ordered list 1772 of options (name-value pairs) that are 1773 passed to the configured task. 1775 ma-task-tags: An optional unordered set of tags that are 1776 reported together with the measurement 1777 results to a collector. 1779 3.9.2. Definition of ma-option-obj 1781 object { 1782 string ma-option-name; 1783 [object ma-option-value;] 1784 } ma-option-obj; 1786 The ma-option-obj models a name-value pair and consists of the 1787 following elements: 1789 ma-option-name: The name of the option. 1791 ma-option-value: The optional value of the option. 1793 The ma-option-obj is used to define Task Configuration Options. Task 1794 Configuration Options are generally task specific. For tasks 1795 associated with an entry in a registry, the registry may define well- 1796 known option names (e.g., the so-called parameters in the IPPM metric 1797 registry [I-D.ietf-ippm-metric-registry]). Control and Reporting 1798 Tasks need to know the Channel they are going to use. The common 1799 option name for specifying the channel is "channel" where the 1800 option's value refers to the name of an ma-channel-obj. 1802 3.10. Common Objects: Registry Information 1804 Tasks and actions can be associated with entries in a registry. A 1805 registry object refers to an entry in a registry (identified by a 1806 URI) and it may define a set of roles. 1808 3.10.1. Definition of ma-registry-obj 1810 object { 1811 uri ma-registry-uri; 1812 [string ma-registry-role<0..*>;] 1813 } ma-registry-obj; 1815 The ma-registry-obj refers to an entry of a registry and it defines 1816 the associated role(s). The ma-registry-obj consists of the 1817 following elements: 1819 ma-registry-uri: A URI identifying an entry in a registry. 1821 ma-registry-role: An optional and possibly empty unordered 1822 set of roles for the identified registry 1823 entry. 1825 3.11. Common Objects: Event Information 1827 The Event information object used throughout the information models 1828 can initially take one of several different forms. Additional forms 1829 may be defined later in order to bind the execution of schedules to 1830 additional events. The initially defined Event forms are: 1832 1. Periodic Timing: Emits multiple events periodically according to 1833 an interval time defined in seconds 1835 2. Calendar Timing: Emits multiple events according to a calendar 1836 based pattern, e.g., 22 minutes past each hour of the day on 1837 weekdays 1839 3. One Off Timing: Emits one event at a specific date and time 1841 4. Immediate: Emits one event as soon as possible 1843 5. Startup: Emits an event whenever the MA is started (e.g., at 1844 device startup) 1846 6. Controller Lost: Emits an event when connectivity to the 1847 controller has been lost 1849 7. Controller Connected: Emits an event when connectivity to the 1850 controller has been (re-)established 1852 Optionally each of the Event options may also specify a randomness 1853 that should be evaluated and applied separately to each indicated 1854 event. This randomness parameter defines a uniform interval in 1855 seconds over which the start of the task is delayed from the starting 1856 times specified by the event object. 1858 Both the Periodic and Calendar timing objects allow for a series of 1859 Actions to be executed. While both have an optional end time, it is 1860 best practice to always configure an end time and refresh the 1861 information periodically to ensure that lost MAs do not continue 1862 their tasks forever. 1864 Startup events are only created on device startup, not when a new 1865 Instruction is transferred to the MA. If scheduled task execution is 1866 desired both on the transfer of the Instruction and on device restart 1867 then both the Immediate and Startup timing needs to be used in 1868 conjunction. 1870 The datetime format used for all elements in the information model 1871 MUST conform to RFC 3339 [RFC3339]. 1873 3.11.1. Definition of ma-event-obj 1874 object { 1875 string ma-event-name; 1876 union { 1877 ma-periodic-obj ma-event-periodic; 1878 ma-calendar-obj ma-event-calendar; 1879 ma-one-off-obj ma-event-one-off; 1880 ma-immediate-obj ma-event-immediate; 1881 ma-startup-obj ma-event-startup; 1882 ma-controller-lost-obj ma-event-controller-lost; 1883 ma-controller-connected-obj ma-event-controller-connected; 1884 } 1885 [int ma-event-random-spread;] 1886 [int ma-event-cycle-interval;] 1887 } ma-event-obj; 1889 The ma-event-obj is the main event object. Event objects are 1890 identified by a name. A generic event object itself contains a more 1891 specific event object. The set of specific event objects should be 1892 extensible. The initial set of specific event objects is further 1893 described below. The ma-event-obj also includes an optional uniform 1894 random spread that can be used to randomize the start times of 1895 schedules triggered by an event. The ma-event-obj consists of the 1896 following elements: 1898 ma-event-name: The name uniquely identifies an event 1899 object. Schedules refer to event 1900 objects by this name. 1902 ma-event-periodic: The ma-event-periodic is present for 1903 periodic timing objects. 1905 ma-event-calendar: The ma-event-calendar is present for 1906 calendar timing objects. 1908 ma-event-one-off: The ma-event-one-off is present for 1909 one-off timing objects. 1911 ma-event-immediate: The ma-event-immediate is present for 1912 immediate event objects. 1914 ma-event-startup: The ma-event-startup is present for 1915 startup event objects. 1917 ma-event-controller-lost: The ma-event-controller-lost is 1918 present for connectivity to 1919 controller lost event objects. 1921 ma-event-controller-connected: The ma-event-controller-connected is 1922 present for connectivity to a 1923 controller established event objects. 1925 ma-event-random-spread: The optional ma-event-random-spread 1926 adds a random delay defined in 1927 seconds to the event object. No 1928 random delay is added if ma-event- 1929 random-spread does not exist. 1931 ma-event-cycle-interval: The optional ma-event-cycle-interval 1932 defines the duration of the time 1933 interval in seconds that is used to 1934 calculate cycle numbers. No cycle 1935 number is calculated if ma-event- 1936 cycle-interval does not exist. 1938 3.11.2. Definition of ma-periodic-obj 1940 object { 1941 [datetime ma-periodic-start;] 1942 [datetime ma-periodic-end;] 1943 int ma-periodic-interval; 1944 } ma-periodic-obj; 1946 The ma-periodic-obj timing object has an optional start and an 1947 optional end time plus a periodic interval. Schedules using an ma- 1948 periodic-obj are started periodically between the start and end time. 1949 The ma-periodic-obj consists of the following elements: 1951 ma-periodic-start: The optional date and time at which 1952 Schedules using this object are first 1953 started. If not present it defaults to 1954 immediate. 1956 ma-periodic-end: The optional date and time at which 1957 Schedules using this object are last 1958 started. If not present it defaults to 1959 indefinite. 1961 ma-periodic-interval: The interval defines the time in seconds 1962 between two consecutive starts of tasks. 1964 3.11.3. Definition of ma-calendar-obj 1966 Calendar Timing supports the routine execution of Schedules at 1967 specific times and/or on specific dates. It can support more 1968 flexible timing than Periodic Timing since the execution of Schedules 1969 does not have to be uniformly spaced. For example a Calendar Timing 1970 could support the execution of a Measurement Task every hour between 1971 6pm and midnight on weekdays only. 1973 Calendar Timing is also required to perform measurements at 1974 meaningful times in relation to network usage (e.g., at peak times). 1975 If the optional timezone offset is not supplied then local system 1976 time is assumed. This is essential in some use cases to ensure 1977 consistent peak-time measurements as well as supporting MA devices 1978 that may be in an unknown timezone or roam between different 1979 timezones (but know their own timezone information such as through 1980 the mobile network). 1982 The calendar elements within the Calendar Timing do not have defaults 1983 in order to avoid accidental high-frequency execution of Tasks. If 1984 all possible values for an element are desired then the wildcard * is 1985 used. 1987 object { 1988 [datetime ma-calendar-start;] 1989 [datetime ma-calendar-end;] 1990 [string ma-calendar-months<0..*>;] 1991 [string ma-calendar-days-of-week<0..*>;] 1992 [string ma-calendar-days-of-month<0..*>;] 1993 [string ma-calendar-hours<0..*>;] 1994 [string ma-calendar-minutes<0..*>;] 1995 [string ma-calendar-seconds<0..*>;] 1996 [int ma-calendar-timezone-offset;] 1997 } ma-calendar-obj; 1999 ma-calendar-start: The optional date and time at which 2000 Schedules using this object are first 2001 started. If not present it defaults to 2002 immediate. 2004 ma-calendar-end: The optional date and time at which 2005 Schedules using this object are last 2006 started. If not present it defaults to 2007 indefinite. 2009 ma-calendar-months: The optional set of months (1-12) on 2010 which tasks scheduled using this object 2011 are started. The wildcard * means all 2012 months. If not present, it defaults to 2013 no months. 2015 ma-calendar-days-of-week: The optional set of days of a week 2016 ("Mon", "Tue", "Wed", "Thu", "Fri", 2017 "Sat", "Sun") on which tasks scheduled 2018 using this object are started. The 2019 wildcard * means all days of the week. 2020 If not present, it defaults to no days. 2022 ma-calendar-days-of-month: The optional set of days of a months 2023 (1-31) on which tasks scheduled using 2024 this object are started. The wildcard 2025 * means all days of a months. If not 2026 present, it defaults to no days. 2028 ma-calendar-hours: The optional set of hours (0-23) on 2029 which tasks scheduled using this object 2030 are started. The wildcard * means all 2031 hours of a day. If not present, it 2032 defaults to no hours. 2034 ma-calendar-minutes: The optional set of minutes (0-59) on 2035 which tasks scheduled using this object 2036 are started. The wildcard * means all 2037 minutes of an hour. If not present, it 2038 defaults to no hours. 2040 ma-calendar-seconds: The optional set of seconds (0-59) on 2041 which tasks scheduled using this object 2042 are started. The wildcard * means all 2043 seconds of an hour. If not present, it 2044 defaults to no seconds. 2046 ma-calendar-timezone-offset: The optional timezone offest in hours. 2047 If not present, it defaults to the 2048 system's local timezone. 2050 If a day of the month is specified that does not exist in the month 2051 (e.g., 29th of Feburary) then those values are ignored. 2053 3.11.4. Definition of ma-one-off-obj 2055 object { 2056 datetime ma-one-off-time; 2057 } ma-one-off-obj; 2059 The ma-one-off-obj timing object specifies a fixed point in time. 2060 Schedules using an ma-one-off-obj are started once at the specified 2061 date and time. The ma-one-off-obj consists of the following 2062 elements: 2064 ma-one-off-time: The date and time at which Schedules using 2065 this object are started. 2067 3.11.5. Definition of ma-immediate-obj 2069 object { 2070 // empty 2071 } ma-immediate-obj; 2073 The ma-immediate-obj event object has no further information 2074 elements. Schedules using an ma-immediate-obj are started as soon as 2075 possible. 2077 3.11.6. Definition of ma-startup-obj 2079 object { 2080 // empty 2081 } ma-startup-obj; 2083 The ma-startup-obj event object has no further information elements. 2084 Schedules or suppressions using an ma-startup-obj are started at MA 2085 initialization time. 2087 3.11.7. Definition of ma-controller-lost-obj 2089 object { 2090 // empty 2091 } ma-controller-lost-obj; 2093 The ma-controller-lost-obj event object has no further information 2094 elements. The ma-controller-lost-obj indicates that connectivity to 2095 the controller has been lost. This is determined by a timer started 2096 after each successful contact with a controller. When the timer 2097 reaches the controller-timeout (measured in seconds), an ma- 2098 controller-lost-obj event is generated. This event may be used to 2099 start a suppression. 2101 3.11.8. Definition of ma-controller-connected-obj 2103 object { 2104 // empty 2105 } ma-controller-connected-obj; 2107 The ma-controller-connected-obj event object has no further 2108 information elements. The ma-controller-connected-obj indicates that 2109 connectivity to the controller has been established again after it 2110 was lost. This event may be used to end a suppression. 2112 4. Example Execution 2114 The example execution has two event sources E1 and E2 and three 2115 schedules S1, S2, and S3. The schedule S3 is started by events of 2116 event source E2 while the schedules S1 and S2 are both started by 2117 events of the event source E1. The schedules S1 and S2 have two 2118 actions each and schedule S3 has a single action. The event source 2119 E2 has no randomization while the event source E1 has the 2120 randomization r. 2122 Figure 2 shows a possible timeline of an execution. The time T is 2123 progressing downwards. The dotted vertial line indicates progress of 2124 time while a dotted horizontal line indicates which schedule are 2125 triggered by an event. Tilded lines indicate data flowing from an 2126 action to another schedule. Actions within a schedule are named A1, 2127 A2, etc. 2129 E2 E1 T S1 S2 S3 2130 sequential parallel pipelined 2131 : 2132 e0 + 2133 : 2134 : 2135 e0+r + .......... + .......... ++ 2136 : | A1 A1 || A2 2137 : + |+ ~~~~~~~> 2138 : | A2 | 2139 : | + ~~~~~~~~> 2140 : + ~~~~~~~~~~~~~~~~~~~~~> 2141 : 2142 : 2143 e1 + 2144 : 2145 e1+r + .......... + .......... ++ 2146 : | A1 A1 || 2147 : | +|~~~~~~~> 2148 : | | A2 2149 : + +~~~~~~~> 2150 : | A2 2151 : + ~~~~~~~~~~~~~~~~~~~~> 2152 e0 + ................................... + 2153 : | A1 2154 e3 + | 2155 e3+r + .......... + .......... ++ | 2156 : | A1 A1 || A2 | 2157 : + ++ ~~~~~~> | 2158 : | A2 + 2159 : + ~~~~~~~~~~~~~~~~~~~~> 2160 V 2162 Figure 2: Example Execution 2164 Note that implementations must handle possible concurrency issues. 2165 In the example execution, action A1 of schedule S3 is consuming the 2166 data that has been forwarded to schedule S3 while additional data is 2167 arriving from action A2 of schedule S2. 2169 5. IANA Considerations 2171 This document makes no request of IANA. 2173 Note to the RFC Editor: this section may be removed on publication as 2174 an RFC. 2176 6. Security Considerations 2178 This Information Model deals with information about the control and 2179 reporting of the Measurement Agent. There are broadly two security 2180 considerations for such an Information Model. Firstly the 2181 Information Model has to be sufficient to establish secure 2182 communication channels to the Controller and Collector such that 2183 other information can be sent and received securely. Additionally, 2184 any mechanisms that the Network Operator or other device 2185 administrator employs to pre-configure the MA must also be secure to 2186 protect unauthorized parties from modifying pre-configuration 2187 information. These mechanisms are important to ensure that the MA 2188 cannot be hijacked, for example to participate in a distributed 2189 denial of service attack. 2191 The second consideration is that no mandated information items should 2192 pose a risk to confidentiality or privacy given such secure 2193 communication channels. For this latter reason items such as the MA 2194 context and MA ID are left optional and can be excluded from some 2195 deployments. This would, for example, allow the MA to remain 2196 anonymous and for information about location or other context that 2197 might be used to identify or track the MA to be omitted or blurred. 2199 The Information Model should support wherever relevant, all the 2200 security and privacy requirements associated with the LMAP Framework. 2202 7. Acknowledgements 2204 Several people contributed to this specification by reviewing early 2205 versions and actively participating in the LMAP working group 2206 (apologies to those unintentionally omitted): Vaibhav Bajpai, Michael 2207 Bugenhagen, Timothy Carey, Alissa Cooper, Kenneth Ko, Al Morton, Dan 2208 Romascanu, Henning Schulzrinne, Andrea Soppera, Barbara Stark, and 2209 Jason Weil. 2211 Trevor Burbridge, Philip Eardley, Marcelo Bagnulo and Juergen 2212 Schoenwaelder worked in part on the Leone research project, which 2213 received funding from the European Union Seventh Framework Programme 2214 [FP7/2007-2013] under grant agreement number 317647. 2216 Juergen Schoenwaelder was partly funded by Flamingo, a Network of 2217 Excellence project (ICT-318488) supported by the European Commission 2218 under its Seventh Framework Programme. 2220 8. References 2222 8.1. Normative References 2224 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2225 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 2226 RFC2119, March 1997, 2227 . 2229 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 2230 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 2231 . 2233 [RFC7594] Eardley, P., Morton, A., Bagnulo, M., Burbridge, T., 2234 Aitken, P., and A. Akhter, "A Framework for Large-Scale 2235 Measurement of Broadband Performance (LMAP)", RFC 7594, 2236 DOI 10.17487/RFC7594, September 2015, 2237 . 2239 8.2. Informative References 2241 [I-D.ietf-ippm-metric-registry] 2242 Bagnulo, M., Claise, B., Eardley, P., Morton, A., and A. 2243 Akhter, "Registry for Performance Metrics", draft-ietf- 2244 ippm-metric-registry-07 (work in progress), July 2016. 2246 [I-D.ietf-lmap-yang] 2247 Schoenwaelder, J. and V. Bajpai, "A YANG Data Model for 2248 LMAP Measurement Agents", draft-ietf-lmap-yang-05 (work in 2249 progress), July 2016. 2251 [RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between 2252 Information Models and Data Models", RFC 3444, DOI 10 2253 .17487/RFC3444, January 2003, 2254 . 2256 [RFC7398] Bagnulo, M., Burbridge, T., Crawford, S., Eardley, P., and 2257 A. Morton, "A Reference Path and Measurement Points for 2258 Large-Scale Measurement of Broadband Performance", RFC 2259 7398, DOI 10.17487/RFC7398, February 2015, 2260 . 2262 Appendix A. Change History 2264 Note to the RFC Editor: this section should be removed on publication 2265 as an RFC. 2267 A.1. Non-editorial changes since -13 2269 o Removed the ma-config-device-id from the ma-config-obj. 2271 o Added ma-config-report-group-id and clarified how two flags ma- 2272 config-report-agent-id and ma-config-report-group-id work. 2274 A.2. Non-editorial changes since -12 2276 o Renamed the ma-metrics-registry-obj to ma-registry-obj since tasks 2277 may refer to different registries (not just a metrics registry). 2279 o Clarifications and bug fixes. 2281 A.3. Non-editorial changes since -11 2283 o Clarifications and bug fixes. 2285 A.4. Non-editorial changes since -10 2287 o Rewrote the text concerning the well-known "channel" option name. 2289 o Added ma-report-result-event-time, ma-report-result-cycle-number, 2290 and ma-event-cycle-interval. 2292 o Added ma-capability-tags. 2294 o Added a new section showing an example execution. 2296 o Several clarifications and bug fixes. 2298 A.5. Non-editorial changes since -09 2300 o Added ma-status-schedule-storage and ma-status-action-storage. 2302 o Removed suppress-by-default. 2304 o Moved ma-report-result-metrics of the ma-report-result-obj to ma- 2305 report-table-metrics of the ma-report-table-obj so that the 2306 relationship between metrics and result tables is clear. 2308 o Added ma-report-conflict-obj. 2310 o Added ma-report-result-status to ma-report-result-obj. 2312 o Several clarifications and bug fixes. 2314 A.6. Non-editorial changes since -08 2316 o Refactored the ma-report-task-obj into the ma-report-result-obj. 2318 o Introduced the ma-report-table-obj so that a result can contain 2319 multiple tables. 2321 o Report schedule, action, and task name as part of the ma-report- 2322 result-obj. 2324 o Report conflicts per ma-report-result-obj and not per ma-report- 2325 row-obj. 2327 o Report the start/end time as part of the ma-report-result-obj. 2329 A.7. Non-editorial changes since -07 2331 o Added ma-schedule-end and ma-schedule-duration. 2333 o Changed the granularity of scheduler timings to seconds. 2335 o Added ma-status-suppression-obj to report the status of 2336 suppressions as done in the YANG data model. 2338 o Added counters to schedule and action status objects to match the 2339 counters in the YANG data model. 2341 o Using tags to pass information such as a measurement cycle 2342 identifier to the collector. 2344 o Using suppression tags and glob-style matching to select schedules 2345 and actions to be suppressed. 2347 A.8. Non-editorial changes since -06 2349 o The default execution mode is pipelined (LI12) 2351 o Added text to define which action consumes data in sequential, 2352 pipelines, and parallel execution mode (LI11) 2354 o Added ma-config-measurement-point, ma-report-measurement-point, 2355 and ma-config-report-measurement-point to configure and report the 2356 measurement point (LI10) 2358 o Turned ma-suppression-obj into a list that uses a start event and 2359 a stop event to define the start and end of suppression; this 2360 unifies the handling of suppression and loss of controller 2361 connectivity (LI09) 2363 o Added ma-controller-lost-obj and ma-controller-ok-obj event 2364 objects (LI09) 2366 o Added ma-status-schedule-obj to report the status of a schedule 2367 and refactored ma-task-status-obj into ma-status-action-obj to 2368 report the status of an action (LI07, LI08) 2370 o Introduced a common ma-metric-registry-obj that identifies a 2371 metric and a set of associated roles and added this object to 2372 expose metric capabilities and to support the configuration of 2373 metrics and to report the metrics used (LI06) 2375 o Introduced ma-capability-obj and ma-capability-task-obj to expose 2376 the capabilities of a measurement agent (LI05) 2378 o Use 'ordered list' or 'unordered set' instead of list, collection, 2379 etc. (LI02) 2381 o Clarification that Actions are part of a Schedule (LI03) 2383 o Deleted terms that are not strictly needed (LI04) 2385 A.9. Non-editorial changes since -05 2387 o A task can now reference multiply registry entries. 2389 o Consistent usage of the term Action and Task. 2391 o Schedules are triggered by Events instead of Timings; Timings are 2392 just one of many possible event sources. 2394 o Actions feed into other Schedules (instead of Actions within other 2395 Schedules). 2397 o Removed the notion of multiple task outputs. 2399 o Support for sequential, parallel, and pipelined execution of 2400 Actions. 2402 Authors' Addresses 2404 Trevor Burbridge 2405 BT 2406 Adastral Park, Martlesham Heath 2407 Ipswich IP5 3RE 2408 United Kingdom 2410 Email: trevor.burbridge@bt.com 2411 Philip Eardley 2412 BT 2413 Adastral Park, Martlesham Heath 2414 Ipswich IP5 3RE 2415 United Kingdom 2417 Email: philip.eardley@bt.com 2419 Marcelo Bagnulo 2420 Universidad Carlos III de Madrid 2421 Av. Universidad 30 2422 Leganes, Madrid 28911 2423 Spain 2425 Email: marcelo@it.uc3m.es 2427 Juergen Schoenwaelder 2428 Jacobs University Bremen 2429 Campus Ring 1 2430 Bremen 28759 2431 Germany 2433 Email: j.schoenwaelder@jacobs-university.de