idnits 2.17.00 (12 Aug 2021) /tmp/idnits18194/draft-ietf-lmap-information-model-09.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 706 has weird spacing: '...ion-obj ma-in...' == Line 891 has weird spacing: '...ask-obj ma-ca...' == Line 912 has weird spacing: '...try-obj ma-ca...' == Line 934 has weird spacing: '...ion-obj ma-st...' == Line 967 has weird spacing: '...ion-obj ma-...' == (4 more instances...) -- The document date (March 21, 2016) is 2251 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Downref: Normative reference to an Informational RFC: RFC 7594 == Outdated reference: draft-ietf-ippm-metric-registry has been published as RFC 8911 == Outdated reference: draft-ietf-lmap-yang has been published as RFC 8194 Summary: 1 error (**), 0 flaws (~~), 10 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Burbridge 3 Internet-Draft P. Eardley 4 Intended status: Standards Track BT 5 Expires: September 22, 2016 M. Bagnulo 6 Universidad Carlos III de Madrid 7 J. Schoenwaelder 8 Jacobs University Bremen 9 March 21, 2016 11 Information Model for Large-Scale Measurement Platforms (LMAP) 12 draft-ietf-lmap-information-model-09 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 September 22, 2016. 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 . . . . . . . . . . 16 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 . . . . . . . 24 84 3.5.7. Definition of ma-interface-obj . . . . . . . . . . . 25 85 3.6. Reporting Information . . . . . . . . . . . . . . . . . . 26 86 3.6.1. Definition of ma-report-obj . . . . . . . . . . . . . 27 87 3.6.2. Definition of ma-report-result-obj . . . . . . . . . 28 88 3.6.3. Definition of ma-report-table-obj . . . . . . . . . . 29 89 3.6.4. Definition of ma-report-row-obj . . . . . . . . . . . 29 90 3.7. Common Objects: Schedules . . . . . . . . . . . . . . . . 30 91 3.7.1. Definition of ma-schedule-obj . . . . . . . . . . . . 31 92 3.7.2. Definition of ma-action-obj . . . . . . . . . . . . . 32 93 3.8. Common Objects: Channels . . . . . . . . . . . . . . . . 33 94 3.8.1. Definition of ma-channel-obj . . . . . . . . . . . . 34 95 3.9. Common Objects: Task Configurations . . . . . . . . . . . 35 96 3.9.1. Definition of ma-task-obj . . . . . . . . . . . . . . 36 97 3.9.2. Definition of ma-option-obj . . . . . . . . . . . . . 37 98 3.10. Common Objects: Registry Information . . . . . . . . . . 37 99 3.10.1. Definition of ma-metric-registry-obj . . . . . . . . 38 100 3.11. Common Objects: Event Information . . . . . . . . . . . . 38 101 3.11.1. Definition of ma-event-obj . . . . . . . . . . . . . 39 102 3.11.2. Definition of ma-periodic-obj . . . . . . . . . . . 40 103 3.11.3. Definition of ma-calendar-obj . . . . . . . . . . . 41 104 3.11.4. Definition of ma-one-off-obj . . . . . . . . . . . . 42 105 3.11.5. Definition of ma-immediate-obj . . . . . . . . . . . 43 106 3.11.6. Definition of ma-startup-obj . . . . . . . . . . . . 43 107 3.11.7. Definition of ma-controller-lost-obj . . . . . . . . 43 108 3.11.8. Definition of ma-controller-connected-obj . . . . . 43 109 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 44 110 5. Security Considerations . . . . . . . . . . . . . . . . . . . 44 111 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 44 112 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 45 113 7.1. Normative References . . . . . . . . . . . . . . . . . . 45 114 7.2. Informative References . . . . . . . . . . . . . . . . . 45 115 Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . 46 116 A.1. Remove suppress-by-default . . . . . . . . . . . . . . . 46 117 A.2. Overlapping schedules/actions are skipped . . . . . . . . 46 118 A.3. Storage usage reporting and control . . . . . . . . . . . 46 119 A.4. Configuration vs. instruction: ma-task-obj . . . . . . . 46 120 A.5. Streamline the reporting model . . . . . . . . . . . . . 46 121 Appendix B. Non-editorial Changes since -08 . . . . . . . . . . 47 122 Appendix C. Non-editorial Changes since -07 . . . . . . . . . . 47 123 Appendix D. Non-editorial Changes since -06 . . . . . . . . . . 47 124 Appendix E. Non-editorial Changes since -05 . . . . . . . . . . 48 125 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 48 127 1. Introduction 129 A large-scale measurement platform is a collection of components that 130 work in a coordinated fashion to perform measurements from a large 131 number of vantage points. The main components of a large-scale 132 measurement platform are the Measurement Agents (hereafter MAs), the 133 Controller(s) and the Collector(s). 135 The MAs are the elements actually performing the measurements. The 136 MAs are controlled by exactly one Controller at a time and the 137 Collectors gather the results generated by the MAs. In a nutshell, 138 the normal operation of a large-scale measurement platform starts 139 with the Controller instructing a set of one or more MAs to perform a 140 set of one or more Measurement Tasks at a certain point in time. The 141 MAs execute the instructions from a Controller, and once they have 142 done so, they report the results of the measurements to one or more 143 Collectors. The overall framework for a Large Measurement platform 144 as used in this document is described in detail in [RFC7594]. 146 A large-scale measurement platform involves basically three types of 147 protocols, namely, a Control protocol (or protocols) between a 148 Controller and the MAs, a Report protocol (or protocols) between the 149 MAs and the Collector(s) and several measurement protocols between 150 the MAs and Measurement Peers (MPs), used to actually perform the 151 measurements. In addition some information is required to be 152 configured on the MA prior to any communication with a Controller. 154 This document defines the information model for both Control and the 155 Report protocols along with pre-configuration information that is 156 required on the MA before communicating with the Controller, broadly 157 named as the LMAP Information Model. The measurement protocols are 158 out of the scope of this document. 160 As defined in [RFC3444], the LMAP Information Model defines the 161 concepts involved in a large-scale measurement platform at a high 162 level of abstraction, independent of any specific implementation or 163 actual protocol used to exchange the information. It is expected 164 that the proposed information model can be used with different 165 protocols in different measurement platform architectures and across 166 different types of MA devices (e.g., home gateway, smartphone, PC, 167 router). A YANG data model implementing the information model can be 168 found in [I-D.ietf-lmap-yang]. 170 The definition of an Information Model serves a number of purposes: 172 1. To guide the standardisation of one or more Control and Report 173 protocols and data models 175 2. To enable high-level inter-operability between different Control 176 and Report protocols by facilitating translation between their 177 respective data models such that a Controller could instruct sub- 178 populations of MAs using different protocols 180 3. To form agreement of what information needs to be held by an MA 181 and passed over the Control and Report interfaces and support the 182 functionality described in the LMAP framework 184 4. Enable existing protocols and data models to be assessed for 185 their suitability as part of a large-scale measurement system 187 2. Notation 189 This document uses a programming language-like notation to define the 190 properties of the objects of the information model. An optional 191 property is enclosed by square brackets, [ ], and a list property is 192 indicated by two numbers in angle brackets, , where m indicates 193 the minimal number of values, and n is the maximum. The symbol * for 194 n means no upper bound. 196 3. LMAP Information Model 198 The information described herein relates to the information stored, 199 received or transmitted by a Measurement Agent as described within 200 the LMAP framework [RFC7594]. As such, some subsets of this 201 information model are applicable to the measurement Controller, 202 Collector and any device management system that pre-configures the 203 Measurement Agent. The information described in these models will be 204 transmitted by protocols using interfaces between the Measurement 205 Agent and such systems according to a Data Model. 207 For clarity the information model is divided into six sections: 209 1. Pre-Configuration Information. Information pre-configured on the 210 Measurement Agent prior to any communication with other 211 components of the LMAP architecture (i.e., the Controller, 212 Collector and Measurement Peers), specifically detailing how to 213 communicate with a Controller and whether the device is enabled 214 to participate as an MA. 216 2. Configuration Information. Update of the pre-configuration 217 information during the registration of the MA or subsequent 218 communication with the Controller, along with the configuration 219 of further parameters about the MA (rather than the Tasks it 220 should perform) that were not mandatory for the initial 221 communication between the MA and a Controller. 223 3. Instruction Information. Information that is received by the MA 224 from the Controller pertaining to the Tasks that should be 225 executed. This includes the task execution Schedules (other than 226 the Controller communication Schedule supplied as 227 (pre)configuration information) and related information such as 228 the Task Configuration, communication Channels to Collectors and 229 schedule Timing information. It also includes Task Suppression 230 information that is used to over-ride normal Task execution. 232 4. Logging Information. Information transmitted from the MA to the 233 Controller detailing the results of any configuration operations 234 along with error and status information from the operation of the 235 MA. 237 5. Capability and Status Information. Information on the general 238 status and capabilities of the MA. For example, the set of 239 measurements that are supported on the device. 241 6. Reporting Information. Information transmitted from the MA to 242 one or more Collectors including measurement results and the 243 context in which they were conducted. 245 In addition the MA may hold further information not described herein, 246 and which may be optionally transferred to or from other systems 247 including the Controller and Collector. One example of information 248 in this category is subscriber or line information that may be 249 extracted by a task and reported by the MA in the reporting 250 communication to a Collector. 252 It should also be noted that the MA may be in communication with 253 other management systems which may be responsible for configuring and 254 retrieving information from the MA device. Such systems, where 255 available, can perform an important role in transferring the pre- 256 configuration information to the MA or enabling/disabling the 257 measurement functionality of the MA. 259 The Information Model is divided into sub-sections for a number of 260 reasons. Firstly the grouping of information facilitates reader 261 understanding. Secondly, the particular groupings chosen are 262 expected to map to different protocols or different transmissions 263 within those protocols. 265 The granularity of data transmitted in each operation of the Control 266 and Report Protocols is not dictated by the Information Model. For 267 example, the Instruction object may be delivered in a single 268 operation. Alternatively, Schedules and Task Configurations may be 269 separated or even each Schedule/Task Configuration may be delivered 270 individually. Similarly the Information Model does not dictate 271 whether data is read, write, or read/write. For example, some 272 Control Protocols may have the ability to read back Configuration and 273 Instruction information which have been previously set on the MA. 274 Lastly, while some protocols may simply overwrite information (for 275 example refreshing the entire Instruction Information), other 276 protocols may have the ability to update or delete selected items of 277 information. 279 The information in these six sections is captured by a number of 280 common information objects. These objects are also described later 281 in this document and comprise of: 283 1. Schedules. A set of Schedules tell the MA to do something. 284 Without a Schedule no Task (from a measurement to reporting or 285 communicating with the Controller) is ever executed. Schedules 286 are used within the Instruction to specify what tasks should be 287 performed, when, and how to direct their results. A Schedule is 288 also used within the pre-Configuration and Configuration 289 information in order to execute the Task or Tasks required to 290 communicate with the Controller. 292 2. Channels. A set of Channel objects are used to communicate with 293 a number of endpoints (i.e., the Controller and Collectors). 294 Each Channel object contains the information required for the 295 communication with a single endpoint such as the target location 296 and security details. 298 3. Task Configurations. A set of Task Configurations is used to 299 configure the Tasks that are run by the MA. This includes the 300 registry entries for the Task and any configuration parameters. 301 Task Configurations are referenced from a Schedule in order to 302 specify what Tasks the MA should execute. 304 4. Events. A set of Event objects that can be referenced from the 305 Schedules. Each Schedule always references exactly one Event 306 object. An Event object specifies either a singleton or series 307 of events that indicate when Tasks should be executed. A 308 commonly used kind of Event objects are Timing objects. 310 Figure 1 illustrates the structure in which these common information 311 objects are referenced. The references are achieved by each object 312 (Task Configuration, Event) being given a short textual name that is 313 used by other objects. The objects shown in parenthesis are part of 314 the internal object structure of a Schedule. Channels are not shown 315 in the diagram since they are only used as an option by selected Task 316 Configurations but are similarly referenced using a short text name. 318 Schedule 319 |-- triggered by --> Event 320 | 321 |-- executes --> Action 1 322 | |-- using --> Task Configuration 323 | | 324 | `-- feeding to --> Destination Schedule 325 : 326 : 327 `-- exceutes --> Action N 328 |-- using --> Task Configuration 329 | 330 `-- feeding to --> Destination Schedule 332 Figure 1: Relationship between Schedules, Events, Actions, Task 333 Configurations, and Destination Schedules 335 It should be clear that the top-level behavior of an MA is simply to 336 execute Schedules. Every Action contained in a Schedule is defined 337 as a Task. As such, these Actions are configured through Task 338 Configurations and executed according to the Event object referenced 339 by the Schedule in which they appear. Note, however, that Actions 340 can have Action specific parameters. 342 Tasks can implement a variety of different types of Actions. While 343 in terms of the Information Model, all Tasks have the same structure, 344 it can help conceptually to think of different Task categories: 346 1. Measurement Tasks measure some aspect of network performance or 347 traffic. They may also capture contextual information from the 348 MA device or network interfaces such as the device type or 349 interface speed. 351 2. Data Transfer Tasks 353 A. Reporting Tasks report the results of Measurement Tasks to 354 Collectors 356 B. Control Task(s) implement the Control Protocol and 357 communicate with the Controller. 359 3. Data Analysis Tasks can exist to analyse data from other 360 Measurement Tasks locally on the MA 362 4. Data Management Tasks may exist to clean-up, filter or compress 363 data on the MA such as Measurement Task results 365 Figure 1 indicates that Actions can produce data that is fed into 366 Destination Schedules. This can by used by Actions implementing 367 Measurement Tasks to feed measurement results to a Schedule that 368 triggers Actions implementing Reporting Tasks. Data fed to a 369 Destination Schedule is consumed by the first Action of the 370 Destination Schedule if the Destination Schedule is using sequential 371 or pipelined execution mode and it is consumed by all Actions of the 372 Destination Schedule if the Destination Schedule is using parallel 373 execution mode. 375 3.1. Pre-Configuration Information 377 This information is the minimal information that needs to be pre- 378 configured to the MA in order for it to successfully communicate with 379 a Controller during the registration process. Some of the Pre- 380 Configuration Information elements are repeated in the Configuration 381 Information in order to allow an LMAP Controller to update these 382 items. The pre-configuration information also contains some elements 383 that are not under the control of the LMAP framework (such as the 384 device identifier and device security credentials). 386 This Pre-Configuration Information needs to include a URL of the 387 initial Controller from where configuration information can be 388 communicated along with the security information required for the 389 communication including the certificate of the Controller (or the 390 certificate of the Certification Authority which was used to issue 391 the certificate for the Controller). All this is expressed as a 392 Channel. While multiple Channels may be provided in the Pre- 393 Configuration Information they must all be associated with a single 394 Controller (e.g., over different interfaces or network protocols). 396 Where the MA pulls information from the Controller, the Pre- 397 Configuration Information also needs to contain the timing of the 398 communication with the Controller as well as the nature of the 399 communication itself (such as the protocol and data to be 400 transferred). The timing is given as a Schedule that executes the 401 Task(s) responsible for communication with the Controller. It is 402 this Task (or Tasks) that implement the Control protocol between the 403 MA and the Controller and utilises the Channel information. The 404 Task(s) may take additional parameters in which case a Task 405 Configuration can also be included. 407 Even where information is pushed to the MA from the Controller 408 (rather than pulled by the MA), a Schedule still needs to be 409 supplied. In this case the Schedule will simply execute a Controller 410 listener task when the MA is started. A Channel is still required 411 for the MA to establish secure communication with the Controller. 413 It can be seen that these Channels, Schedules and Task Configurations 414 for the initial MA-Controller communication are no different in terms 415 of the Information Model to any other Channel, Schedule or Task 416 Configuration that might execute a Measurement Task or report the 417 measurement results (as described later). 419 The MA may be pre-configured with an MA ID, or may use a Device ID in 420 the first Controller contact before it is assigned an MA ID. The 421 Device ID may be a MAC address or some other device identifier 422 expressed as a URI. If the MA ID is not provided at this stage then 423 it must be provided by the Controller during Configuration. 425 3.1.1. Definition of ma-preconfig-obj 427 object { 428 [uuid ma-preconfig-agent-id;] 429 ma-task-obj ma-preconfig-control-tasks<1..*>; 430 ma-channel-obj ma-preconfig-control-channels<1..*>; 431 ma-schedule-obj ma-preconfig-control-schedules<1..*>; 432 [uri ma-preconfig-device-id;] 433 credentials ma-preconfig-credentials; 434 } ma-preconfig-obj; 436 The ma-preconfig-obj is essentially a subset of the ma-config-obj 437 described below. The ma-preconfig-obj consists of the following 438 elements: 440 ma-preconfig-agent-id: An optional uuid uniquely identifying 441 the measurement agent. 443 ma-preconfig-control-tasks: An unordered set of tasks objects. 445 ma-preconfig-control-channels: An unordered set of channel objects. 447 ma-preconfig-control-schedules: An unordered set of scheduling 448 objects. 450 ma-preconfig-device-id: An optional identifier for the 451 device. 453 ma-preconfig-credentials: The security credentials used by the 454 measurement agent. 456 3.2. Configuration Information 458 During registration or at any later point at which the MA contacts 459 the Controller (or vice-versa), the choice of Controller, details for 460 the timing of communication with the Controller or parameters for the 461 communication Task(s) can be changed (as captured by the Channels, 462 Schedules and Task Configurations objects). For example the pre- 463 configured Controller (specified as a Channel or Channels) may be 464 over-ridden with a specific Controller that is more appropriate to 465 the MA device type, location or characteristics of the network (e.g., 466 access technology type or broadband product). The initial 467 communication Schedule may be over-ridden with one more relevant to 468 routine communications between the MA and the Controller. 470 While some Control protocols may only use a single Schedule, other 471 protocols may use several Schedules (and related data transfer Tasks) 472 to update the Configuration Information, transfer the Instruction 473 Information, transfer Capability and Status Information and send 474 other information to the Controller such as log or error 475 notifications. Multiple Channels may be used to communicate with the 476 same Controller over multiple interfaces (e.g., to send logging 477 information over a different network). 479 In addition the MA will be given further items of information that 480 relate specifically to the MA rather than the measurements it is to 481 conduct or how to report results. The assignment of an ID to the MA 482 is mandatory. If the MA Agent ID was not optionally provided during 483 the pre-configuration then one must be provided by the Controller 484 during Configuration. Optionally a Group ID may also be given which 485 identifies a group of interest to which that MA belongs. For example 486 the group could represent an ISP, broadband product, technology, 487 market classification, geographic region, or a combination of 488 multiple such characteristics. Where the Measurement Group ID is set 489 an additional flag (the Report MA ID flag) is required to control 490 whether the Measurement Agent ID is also to be reported. The 491 reporting of a Group ID without the MA ID allows the MA to remain 492 anonymous, which may be particularly useful to prevent tracking of 493 mobile MA devices. 495 Optionally an MA can also be configured to stop executing any 496 Instruction Schedule if the Controller is unreachable. This can be 497 used as a fail-safe to stop Measurement and other Tasks being 498 conducted when there is doubt that the Instruction Information is 499 still valid. This is simply represented as a time window in seconds 500 since the last communication with the Controller after which 501 Instruction Schedules are to be suspended. The appropriate value of 502 the time window will depend on the specified communication Schedule 503 with the Controller and the duration for which the system is willing 504 to tolerate continued operation with potentially stale Instruction 505 Information. 507 While Pre-Configuration Information is persistent upon device reset 508 or power cycle, the persistency of the Configuration Information may 509 be device dependent. Some devices may revert back to their pre- 510 configuration state upon reboot or factory reset, while other devices 511 may store all Configuration and Instruction information in persistent 512 storage. A Controller can check whether an MA has the latest 513 Configuration and Instruction information by examining the Capability 514 and Status information for the MA. 516 It should be noted that control schedules and tasks cannot be 517 suppressed as evidenced by the lack of suppression information in the 518 Configuration. The control schedule must only reference tasks listed 519 as control tasks (i.e., within the Configuration information). Any 520 suppress-by-default flag against control tasks will be ignored. 522 3.2.1. Definition of ma-config-obj 524 object { 525 uuid ma-config-agent-id; 526 ma-task-obj ma-config-control-tasks<1..*>; 527 ma-channel-obj ma-config-control-channels<1..*>; 528 ma-schedule-obj ma-config-control-schedules<1..*>; 529 [uri ma-config-device-id;] 530 credentials ma-config-credentials; 531 [string ma-config-group-id;] 532 [string ma-config-measurement-point;] 533 [boolean ma-config-report-agent-id;] 534 [boolean ma-config-report-measurement-point;] 535 [int ma-config-controller-timeout;] 536 } ma-config-obj; 538 The ma-config-obj consists of the following elements: 540 ma-config-agent-id: A uuid uniquely identifying the 541 measurement agent. 543 ma-config-control-tasks: An unordered set of task objects. 545 ma-config-control-channels: An unordered set of channel 546 objects. 548 ma-config-control-schedules: An unordered set of scheduling 549 objects. 551 ma-config-device-id: An optional identifier for the 552 device. 554 ma-config-credentials: The security credentials used by 555 the measurement agent. 557 ma-config-group-id: An optional identifier of the 558 group of measurement agents this 559 measurement agent belongs to. 561 ma-config-measurement-point: An optional identifier for the 562 measurement point indicating 563 where the measurement agent is 564 located on a path (see [RFC7398] 565 for further details). 567 ma-config-report-agent-id: An optional flag indicating 568 whether the identifier (ma- 569 config-agent-id) should be 570 included in reports. The default 571 value is false. 573 ma-config-report-measurement-point: An optional flag indicating 574 whether the measurement point 575 (ma-config-measurement-point) 576 should be included in reports. 577 The default value is false. 579 ma-config-controller-timeout: A timer is started after each 580 successful contact with a 581 controller. When the timer 582 reaches the controller-timeout 583 (measured in seconds), an event 584 is raised indicating that 585 connectivity to the controller 586 has been lost (see ma-controller- 587 lost-obj). 589 3.3. Instruction Information 591 The Instruction information model has four sub-elements: 593 1. Instruction Task Configurations 595 2. Report Channels 597 3. Instruction Schedules 599 4. Suppression 601 The Instruction supports the execution of all Tasks on the MA except 602 those that deal with communication with the Controller (specified in 603 (pre-)configuration information). The Tasks are configured in 604 Instruction Task Configurations and included by reference in 605 Instruction Schedules that specify when to execute them. The results 606 can be communicated to other Schedules or a Task may implement a 607 Reporting Protocol and communicate results over Report Channels. 608 Suppression is used to temporarily stop the execution of new Tasks as 609 specified by the Instruction Schedules (and optionally to stop 610 ongoing Tasks). 612 A Task Configuration is used to configure the mandatory and optional 613 parameters of a Task. It also serves to instruct the MA about the 614 Task including the ability to resolve the Task to an executable and 615 specifying the schema for the Task parameters. 617 A Report Channel defines how to communicate with a single remote 618 system specified by a URL. A Report Channel is used to send results 619 to single Collector but is no different in terms of the Information 620 Model to the Control Channel used to transfer information between the 621 MA and the Controller. Several Report Channels can be defined to 622 enable results to be split or duplicated across different 623 destinations. A single Channel can be used by multiple (reporting) 624 Task Configurations to transfer data to the same Collector. A single 625 Reporting Task Configuration can also be included in multiple 626 Schedules. E.g., a single Collector may receive data at three 627 different cycle rates, one Schedule reporting hourly, another 628 reporting daily and a third specifying that results should be sent 629 immediately for on-demand measurement tasks. Alternatively multiple 630 Report Channels can be used to send Measurement Task results to 631 different Collectors. The details of the Channel element is 632 described later as it is common to several objects. 634 Instruction Schedules specify which Actions to execute according to a 635 given triggering Event. An Action is a Task with additional specific 636 parameters. An Event can trigger the execution of a single Action or 637 it can trigger a repeated series of Actions. The Schedule also 638 specifies how to link Tasks output data to other Schedules. 640 Measurement Suppression information is used to over-ride the 641 Instruction Schedule and temporarily stop measurements or other Tasks 642 from running on the MA for a defined or indefinite period. While 643 conceptually measurements can be stopped by simply removing them from 644 the Measurement Schedule, splitting out separate information on 645 Measurement Suppression allows this information to be updated on the 646 MA on a different timing cycle or protocol implementation to the 647 Measurement Schedule. It is also considered that it will be easier 648 for a human operator to implement a temporary explicit suppression 649 rather than having to move to a reduced Schedule and then roll-back 650 at a later time. 652 The explicit Suppression instruction message is able to simply 653 enable/disable all Instruction Tasks (that are enabled for default 654 suppression) as well as having fine control on which Tasks are 655 suppressed. Suppression of both specified Task Configurations and 656 Measurement Schedules is supported. Support for disabling specific 657 Task Configurations allows malfunctioning or mis-configured Tasks or 658 Task Configurations that have an impact on a particular part of the 659 network infrastructure (e.g., a particular Measurement Peer) to be 660 targeted. Support for disabling specific Schedules allows for 661 particularly heavy cycles or sets of less essential Measurement Tasks 662 to be suppressed quickly and effectively. Note that Suppression has 663 no effect on either Controller Tasks or Controller Schedules. 665 When no tasks or schedules are explicitly listed, all Instruction 666 tasks will be suppressed (or not) as indicated by the suppress-by- 667 default flag in the Task Configuration. If tasks or schedules are 668 listed explicitly then only these listed tasks or schedules will be 669 suppressed regardless of the suppress-by-default flag. If both 670 individual tasks and individual schedules are listed then only the 671 listed schedules, plus the listed tasks where present in other 672 schedules, will be suppressed regardless of the suppress-by-default 673 flag. 675 Suppression stops new Tasks from executing. In addition, the 676 Suppression information also supports an additional Boolean that is 677 used to select whether on-going tasks are also to be terminated. 679 Unsuppression is achieved through either overwriting the Measurement 680 Suppression information (e.g., changing 'enabled' to False) or 681 through the use of an End time such that the Measurement Suppression 682 will no longer be in effect beyond this time. The datetime format 683 used for all elements in the information model (e.g., the suppression 684 start and end dates) MUST conform to RFC 3339 [RFC3339]. 686 The goal when defining these four different elements is to allow each 687 part of the information model to change without affecting the other 688 three elements. For example it is envisaged that the Report Channels 689 and the set of Task Configurations will be relatively static. The 690 Instruction Schedule, on the other hand, is likely to be more 691 dynamic, as the measurement panel and test frequency are changed for 692 various business goals. Another example is that measurements can be 693 suppressed with a Suppression command without removing the existing 694 Instruction Schedules that would continue to apply after the 695 Suppression expires or is removed. In terms of the Controller-MA 696 communication this can reduce the data overhead. It also encourages 697 the re-use of the same standard Task Configurations and Reporting 698 Channels to help ensure consistency and reduce errors. 700 3.3.1. Definition of ma-instruction-obj 702 object { 703 ma-task-obj ma-instruction-tasks<0..*>; 704 ma-channel-obj ma-instruction-channels<0..*>; 705 ma-schedule-obj ma-instruction-schedules<0..*>; 706 [ma-suppression-obj ma-instruction-suppressions<0..*>;] 707 } ma-instruction-obj; 709 An ma-instruction-obj consists of the following elements: 711 ma-instruction-tasks: A possibly empty unordered set of task 712 objects. 714 ma-instruction-channels: A possibly empty unordered set of 715 channel objects. 717 ma-instruction-schedules: A possibly empty unordered set of 718 schedule objects. 720 ma-instruction-suppressions: An optional possibly empty unordered 721 set of suppression objects. 723 3.3.2. Definition of ma-suppression-obj 725 object { 726 string ma-suppression-name; 727 [ma-event-obj ma-suppression-start;] 728 [ma-event-obj ma-suppression-end;] 729 [string ma-suppression-match<0..*>;] 730 [boolean ma-suppression-stop-running;] 731 } ma-suppression-obj; 733 The ma-suppression-obj controls the suppression of schedules or 734 actions and consists of the following elements: 736 ma-suppression-name: A name uniquely identifying a 737 suppression. 739 ma-suppression-start: The optional event indicating when 740 suppression starts. The default value 741 is 'immediate'. 743 ma-suppression-end: The optional event indicating when 744 suppression ends. The default value is 745 'indefinite'. 747 ma-suppression-match: An optional and possibly empty 748 unordered set of match pattern. 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. If not 755 present, the suppression affects 756 actions that refer to a task with 757 suppress-by-default set to true. 758 Pattern matching is done using glob 759 style pattern (see below). 761 ma-suppression-stop-running: An optional boolean indicating whether 762 suppression will stop any running 763 schedules or actions. The default 764 value for this boolean is false. 766 Glob style pattern matching is following POSIX.2 fnmatch() without 767 special treatment of file paths: 769 * matches a sequence of characters 770 ? matches a single character 771 [seq] matches any character in seq 772 [!seq] matches any character not in seq 774 A backslash followed by a character matches the following character. 775 In particular: 777 \* matches * 778 \? matches ? 779 \\ matches \ 781 A sequence seq may be a sequence of characters (e.g., [abc] or a 782 range of characters (e.g., [a-c]). 784 3.4. Logging Information 786 The MA may report on the success or failure of Configuration or 787 Instruction communications from the Controller. In addition further 788 operational logs may be produced during the operation of the MA and 789 updates to capabilities may also be reported. Reporting this 790 information is achieved in exactly the same manner as scheduling any 791 other Task. We make no distinction between a Measurement Task 792 conducting an active or passive network measurement and one which 793 solely retrieves static or dynamic information from the MA such as 794 capabilities or logging information. One or more logging tasks can 795 be programmed or configured to capture subsets of the Logging 796 Information. These logging tasks are then executed by Schedules 797 which also specify that the resultant data is to be transferred over 798 the Controller Channels. 800 The type of Logging Information will fall into three different 801 categories: 803 1. Success/failure/warning messages in response to information 804 updates from the Controller. Failure messages could be produced 805 due to some inability to receive or parse the Controller 806 communication, or if the MA is not able to act as instructed. 807 For example: 809 * "Measurement Schedules updated OK" 811 * "Unable to parse JSON" 813 * "Missing mandatory element: Measurement Timing" 815 * "'Start' does not conform to schema - expected datetime" 817 * "Date specified is in the past" 819 * "'Hour' must be in the range 1..24" 821 * "Schedule A refers to non-existent Measurement Task 822 Configuration" 824 * "Measurement Task Configuration X registry entry Y not found" 826 * "Updated Measurement Task Configurations do not include M used 827 by Measurement Schedule N" 829 2. Operational updates from the MA. For example: 831 * "Out of memory: cannot record result" 833 * "Collector 'collector.example.com' not responding" 835 * "Unexpected restart" 837 * "Suppression timeout" 839 * "Failed to execute Measurement Task Configuration H" 841 3. Status updates from the MA. For example: 843 * "Device interface added: eth3" 845 * "Supported measurements updated" 847 * "New IP address on eth0: xxx.xxx.xxx.xxx" 849 This Information Model document does not detail the precise format of 850 logging information since it is to a large extent protocol and MA 851 specific. However, some common information can be identified. 853 3.4.1. Definition of ma-log-obj 855 object { 856 uuid ma-log-agent-id; 857 datetime ma-log-event-time; 858 code ma-log-code; 859 string ma-log-description; 860 } ma-log-obj; 862 The ma-log-obj models the generic aspects of a logging object and 863 consists of the following elements: 865 ma-log-agent-id: A uuid uniquely identifying the measurement 866 agent. 868 ma-log-event-time: The date and time of the event reported in 869 the logging object. 871 ma-log-code: A machine readable code describing the 872 event. 874 ma-log-description: A human readable description of the event. 876 3.5. Capability and Status Information 878 The MA will hold Capability Information that can be retrieved by a 879 Controller. Capabilities include the device interface details 880 available to Measurement Tasks as well as the set of Measurement 881 Tasks/Roles (specified by registry entries) that are actually 882 installed or available on the MA. Status information includes the 883 times that operations were last performed such as contacting the 884 Controller or producing Reports. 886 3.5.1. Definition of ma-capability-obj 887 object { 888 string ma-capability-hardware; 889 string ma-capability-firmware; 890 string ma-capability-version; 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-tasks: An optional unordered set of capability 906 objects for each supported task. 908 3.5.2. Definition of ma-capability-task-obj 910 object { 911 string ma-capability-task-name; 912 ma-metric-registry-obj ma-capability-task-metrics<0..*>; 913 string ma-capability-task-version; 914 } ma-capability-task-obj; 916 The ma-capability-task-obj provides information about the capability 917 of a task and consists of the following elements: 919 ma-capability-task-name: A name uniquely identifying a task. 921 ma-capability-task-metrics: A possibly empty unordered set of 922 registered metrics and associated roles 923 this task implements. 925 ma-capability-task-version: The version of the measurement task. 927 3.5.3. Definition of ma-status-obj 928 object { 929 uuid ma-status-agent-id; 930 uri ma-status-device-id; 931 datetime ma-status-last-started; 932 ma-interface-obj ma-status-interfaces<0..*>; 933 [ma-status-schedule-obj ma-status-schedules<0..*>;] 934 [ma-status-suppression-obj ma-status-suppressions<0..*>;] 935 } ma-status-obj; 937 The ma-status-obj provides status information about the measurement 938 agent and consists of the following elements: 940 ma-status-agent-id: A uuid uniquely identifying the measurement 941 agent. 943 ma-status-device-id: A URI identifying the device. 945 ma-status-last-started: The date and time the measurement agent 946 last started. 948 ma-status-interfaces: An unordered set of network interfaces 949 available on the device. 951 ma-status-schedules: An optional unordered set of status objects 952 for each schedule. 954 ma-status-suppressions: An optional unordered set of status objects 955 for each suppression. 957 3.5.4. Definition of ma-status-schedule-obj 959 object { 960 string ma-status-schedule-name; 961 string ma-status-schedule-state; 962 counter ma-status-schedule-invocations; 963 counter ma-status-schedule-suppressions; 964 counter ma-status-schedule-overlaps; 965 counter ma-status-schedule-failures; 966 datetime ma-status-schedule-last-invocation; 967 [ma-status-action-obj ma-status-schedule-actions<0..*>;] 968 } ma-status-schedule-obj; 970 The ma-status-schedule-obj provides status information about that 971 status of a schedule and consists of the following elements: 973 ma-status-schedule-name: The name of the schedule this 974 status object refers to. 976 ma-status-schedule-state: The state of the schedule. The 977 value 'enabled' indicates that 978 the schedule is currently 979 enabled. The value 'suppressed' 980 indicates that the schedule is 981 currently suppressed. The value 982 'disabled' indicates that the 983 schedule is currently disabled. 984 The value 'running' indicates 985 that the schedule is currently 986 running. 988 ma-status-schedule-invocations Number of invocations of this 989 schedule. This counter does not 990 include suppressed invocations or 991 invocations that were prevented 992 due to an overlap with a previous 993 invocation of this schedule. 995 ma-status-schedule-suppressions Number of suppressed executions 996 of this schedule. 998 ma-status-schedule-overlaps Number of executions prevented 999 due to overlaps with a previous 1000 invocation of this schedule. 1002 ma-status-schedule-failures Number of failed executions of 1003 this schedule. A failed 1004 execution is an execution where 1005 at least one action failed. 1007 ma-status-schedule-last-invocation: The date and time of the last 1008 invocation of this schedule. 1010 ma-status-schedule-last-invocation: The date and time of the last 1011 invocation of this schedule. 1013 ma-status-schedule-actions: An optional ordered list of 1014 status objects for each action of 1015 the schedule. 1017 3.5.5. Definition of ma-status-action-obj 1018 object { 1019 string ma-status-action-name; 1020 string ma-status-action-state; 1021 counter ma-status-action-invocations; 1022 counter ma-status-action-suppressions; 1023 counter ma-status-action-overlaps; 1024 counter ma-status-action-failures; 1025 datetime ma-status-action-last-invocation; 1026 datetime ma-status-action-last-completion; 1027 int ma-status-action-last-status; 1028 string ma-status-action-last-message; 1029 datetime ma-status-action-last-failed-completion; 1030 int ma-status-action-last-failed-status; 1031 string ma-status-action-last-failed-message; 1032 } ma-status-action-obj; 1034 The ma-status-action-obj provides status information about an action 1035 of a schedule and consists of the following elements: 1037 ma-status-action-name: The name of the action of a 1038 schedule this status object 1039 refers to. 1041 ma-status-action-state: The state of the action. 1042 The value 'enabled' 1043 indicates that the action is 1044 currently enabled. The 1045 value 'suppressed' indicates 1046 that the action is currently 1047 suppressed. The value 1048 'disabled' indicates that 1049 the action is currently 1050 disabled. The value 1051 'running' indicates that the 1052 action is currently running. 1054 ma-status-schedule-invocations Number of invocations of 1055 this action. This counter 1056 does not include suppressed 1057 invocations or invocations 1058 that were prevented due to 1059 an overlap with a previous 1060 invocation of this action. 1062 ma-status-schedule-suppressions Number of suppressed 1063 executions of this action. 1065 ma-status-schedule-overlaps Number of executions 1066 prevented due to overlaps 1067 with a previous invocation 1068 of this action. 1070 ma-status-schedule-failures Number of failed executions 1071 of this action. 1073 ma-status-action-last-invocation: The date and time of the 1074 last invocation of this 1075 action. 1077 ma-status-action-last-completion: The date and time of the 1078 last completion of this 1079 action. 1081 ma-status-action-last-status: The status code returned by 1082 the last execution of this 1083 action. 1085 ma-status-action-last-message: The status message produced 1086 by the last execution of 1087 this action. 1089 ma-status-action-last-failed-completion: The date and time of the 1090 last failed completion of 1091 this action. 1093 ma-status-action-last-failed-status: The status code returned by 1094 the last failed execution of 1095 this action. 1097 ma-status-action-last-failed-message: The status message produced 1098 by the last failed execution 1099 of this action. 1101 3.5.6. Definition of ma-status-suppression-obj 1103 object { 1104 string ma-status-suppression-name; 1105 string ma-status-suppression-state; 1106 } ma-status-suppression-obj; 1108 The ma-status-suppression-obj provides status information about that 1109 status of a suppression and consists of the following elements: 1111 ma-status-schedule-name: The name of the suppression this status 1112 object refers to. 1114 ma-status-schedule-state: The state of the suppression. The value 1115 'enabled' indicates that the suppression 1116 is currently enabled. The value 'active 1117 indicates that the suppression is 1118 currently active. The value 'disabled' 1119 indicates that the suppression is 1120 currently disabled. 1122 3.5.7. Definition of ma-interface-obj 1124 object { 1125 string ma-interface-name; 1126 string ma-interface-type; 1127 [int ma-interface-speed;] 1128 [string ma-interface-link-layer-address;] 1129 [ip-address ma-interface-ip-addresses<0..*>;] 1130 [ip-address ma-interface-gateways<0..*>;] 1131 [ip-address ma-interface-dns-servers<0..*>;] 1132 } ma-interface-obj; 1134 The ma-interface-obj provides status information about network 1135 interfaces and consists of the following elements: 1137 ma-interface-name: A name uniquely identifying a 1138 network interface. 1140 ma-interface-type: The type of the network interface. 1142 ma-interface-speed: An optional indication of the speed 1143 of the interface (measured in bits- 1144 per-second). 1146 ma-interface-link-layer-address: An optional link-layer address of 1147 the interface. 1149 ma-interface-ip-addresses: An optional ordered list of IP 1150 addresses assigned to the 1151 interface. 1153 ma-interface-gateways: An optional ordered list of 1154 gateways assigned to the interface. 1156 ma-interface-dns-servers: An optional ordered list of DNS 1157 servers assigned to the interface. 1159 3.6. Reporting Information 1161 At a point in time specified by a Schedule, the MA will execute a 1162 task or tasks that communicate a set of measurement results to the 1163 Collector. These Reporting Tasks will be configured to transmit task 1164 results over a specified Report Channel to a Collector. 1166 It should be noted that the output from Tasks does not need to be 1167 sent to communication Channels. It can alternatively, or 1168 additionally, be sent to other Tasks on the MA. This facilitates 1169 using a first Measurement Task to control the operation of a later 1170 Measurement Task (such as first probing available line speed and then 1171 adjusting the operation of a video testing measurement) and also to 1172 allow local processing of data to output alarms (e.g., when 1173 performance drops from earlier levels). Of course, subsequent Tasks 1174 also include Tasks that implement the reporting protocol(s) and 1175 transfer data to one or more Collector(s). 1177 The Report generated by a Reporting Task is structured hierarchically 1178 to avoid repetition of report header and Measurement Task 1179 Configuration information. The report starts with the timestamp of 1180 the report generation on the MA and details about the MA including 1181 the optional Measurement Agent ID and Group ID (controlled by the 1182 Configuration Information). 1184 Much of the report Information is optional and will depend on the 1185 implementation of the Reporting Task and any parameters defined in 1186 the Task Configuration for the Reporting Task. For example some 1187 Reporting Tasks may choose not to include the Measurement Task 1188 Configuration or scheduled task parameters, while others may do so 1189 dependent on the Controller setting a configurable parameter in the 1190 Task Configuration. 1192 It is possible for a Reporting Task to send just the Report header 1193 (datetime and optional agent ID and/or Group ID) if no measurement 1194 data is available. Whether to send such empty reports again is 1195 dependent on the implementation of the Reporting Task and potential 1196 Task Configuration parameter. 1198 The handling of measurement data on the MA before generating a Report 1199 and transfer from the MA to the Collector is dependent on the 1200 implementation of the device, MA and/or scheduled Tasks and not 1201 defined by the LMAP standards. Such decisions may include limits to 1202 the measurement data storage and what to do when such available 1203 storage becomes depleted. 1205 No context information, such as line speed or broadband product are 1206 included within the report header information as this data is 1207 reported by individual tasks at the time they execute. Either a 1208 Measurement Task can report contextual parameters that are relevant 1209 to that particular measurement, or specific tasks can be used to 1210 gather a set of contextual and environmental data. at certain times 1211 independent of the reporting schedule. 1213 After the report header information the results are reported grouped 1214 according to different Measurement Task Configurations. Each Task 1215 section optionally starts with replicating the Measurement Task 1216 Configuration information before the result headers (titles for data 1217 columns) and the result data rows. The Options reported are those 1218 used for the scheduled execution of the Measurement Task and 1219 therefore include the Options specified in the Task Configuration as 1220 well as additional Options specified in the Scheduled Task. The 1221 Scheduled Task Options are appended to the Task Configuration Options 1222 in exactly the same order as they were provided to the Task during 1223 execution. 1225 The result row data includes a time for the start of the measurement 1226 and optionally an end time where the duration also needs to be 1227 considered in the data analysis. 1229 Some Measurement Tasks may optionally include an indication of the 1230 cross-traffic although the definition of cross-traffic is left up to 1231 each individual Measurement Task. Some Measurement Tasks may also 1232 output other environmental measures in addition to cross-traffic such 1233 as CPU utlilisation or interface speed. 1235 Where the Configuration and Instruction information represent 1236 information transmitted via the Control Protocol, the Report 1237 represents the information that is transmitted via the Report 1238 Protocol. It is constructed at the time of sending a report and 1239 represents the inherent structure of the information that is sent to 1240 the Collector. 1242 3.6.1. Definition of ma-report-obj 1244 object { 1245 datetime ma-report-date; 1246 [uuid ma-report-agent-id;] 1247 [string ma-report-group-id;] 1248 [string ma-report-measurement-point;] 1249 [ma-report-result-obj ma-report-results<0..*>;] 1250 } ma-report-obj; 1252 The ma-report-obj provides the meta-data of a single report and 1253 consists of the following elements: 1255 ma-report-date: The date and time when the report was 1256 sent to a collector. 1258 ma-report-agent-id: An optional uuid uniquely identifying 1259 the measurement agent. 1261 ma-report-group-id: An optional identifier of the group of 1262 measurement agents this measurement 1263 agent belongs to. 1265 ma-report-measurement-point: An optional identifier for the 1266 measurement point indicating where the 1267 measurement agent is located on a path 1268 (see [RFC7398] for further details). 1270 ma-report-results: An optional and possibly empty 1271 unordered set of result objects. 1273 3.6.2. Definition of ma-report-result-obj 1275 object { 1276 string ma-report-result-schedule-name; 1277 string ma-report-result-action-name; 1278 string ma-report-result-task-name; 1279 [ma-metric-registry-obj ma-report-result-metrics<0..*>;] 1280 [ma-option-obj ma-report-result-options<0..*>;] 1281 [string ma-report-result-tags<0..*>;] 1282 datetime ma-report-result-start-time; 1283 [datetime ma-report-result-end-time;] 1284 string ma-report-result-conflicts<0..*>; 1285 [ma-report-table-obj ma-report-result-tables<0..*>;] 1286 } ma-report-result-obj; 1288 The ma-report-result-obj provides the meta-data of a result report of 1289 a single executed action. It consists of the following elements: 1291 ma-report-result-schedule-name: The name of the schedule that 1292 produced the result. 1294 ma-report-result-action-name: The name of the action in the 1295 schedule that produced the result. 1297 ma-report-result-task-name: The name of the task that produced 1298 the result. 1300 ma-report-result-metrics: An optional and possibly empty 1301 unordered set of registered metrics 1302 and associated rulels that are 1303 reported. 1305 ma-report-result-options: An optional ordered joined list of 1306 options provided by the task object 1307 and the action object. 1309 ma-report-result-tags: An optional unordered set of tags. 1310 This is the joined set of tags 1311 defined for the task object and the 1312 action object. 1314 ma-report-result-start-time: The date and time of the start of the 1315 measurement task that produced the 1316 reported result values. 1318 ma-report-result-end-time: An optional date and time indicating 1319 when the measurement task finished. 1321 ma-report-result-conflicts: A possibly empty set of names of 1322 tasks that might have impacted the 1323 measurement results being reported. 1325 ma-report-result-tables: An optional and possibly empty 1326 unordered set of result tables. 1328 3.6.3. Definition of ma-report-table-obj 1330 object { 1331 [string] ma-report-table-column-labels<0..*>;] 1332 [ma-report-row-obj ma-report-table-rows<0..*>;] 1333 } ma-report-table-obj; 1335 The ma-report-table-obj represents a result table and consists of the 1336 following elements: 1338 ma-report-table-column-labels: An optional and possibly empty 1339 ordered list of column labels. 1341 ma-report-table-rows: A possibly empty ordered list of 1342 result rows. 1344 3.6.4. Definition of ma-report-row-obj 1346 object { 1347 data ma-report-row-values<0..*>; 1348 } ma-report-row-obj; 1350 The ma-report-row-obj represents a result row and consists of the 1351 following elements: 1353 ma-report-row-values: A possibly empty ordered list of result 1354 values. When present, it contains an 1355 ordered list of values that align to the 1356 set of column labels for the report. 1358 3.7. Common Objects: Schedules 1360 A Schedule specifies the execution of a single or repeated series of 1361 Actions. An Action is a Task with additional specific parameters. 1362 Each Schedule contains basically two elements: an ordered list of 1363 Actions to be executed and an Event object for the Schedule. The 1364 Schedule states what Actions to run (with what configuration) and 1365 when to run the Actions. 1367 Multiple Actions contained as an ordered list of a single Measurement 1368 Schedule will be executed according to the execution mode of the 1369 Schedule. In sequential mode, Actions will be executed sequentially 1370 and in parallel mode, all Actions will be executed concurrently. In 1371 pipelined mode, data produced by one Action is passed to the 1372 subsequent Action. Actions contained in different Schedules execute 1373 in parallel with such conflicts being reported in the Reporting 1374 Information where necessary. If two or more Schedules have the same 1375 start time, then the two will execute in parallel. There is no 1376 mechanism to prioritise one schedule over another or to mutex 1377 scheduled tasks. 1379 As well as specifying which Actions to execute, the Schedule also 1380 specifies how to link the data outputs from each Action to other 1381 Schedules. Specifying this within the Schedule allows the highest 1382 level of flexibility since it is even possible to send the output 1383 from different executions of the same Task Configuration to different 1384 destinations. A single Task producing multiple different outputs is 1385 expected to properly tag the different result. An Action receiving 1386 the output can then filter the results based on the tag if necessary. 1387 For example, a Measurement Task might report routine results to a 1388 data Reporting Task in a Schedule that communicates hourly via the 1389 Broadband PPP interface, but also outputs emergency conditions via an 1390 alarm Reporting Task in a different Schedule communicating 1391 immediately over a GPRS channel. Note that task-to-task data 1392 transfer is always specified in association with the scheduled 1393 execution of the sending task - there is no need for a corresponding 1394 input specification for the receiving task. While it is likely that 1395 an MA implementation will use a queue mechanism between the Schedules 1396 or Actions, this Information Model does not mandate or define a 1397 queue, or any potential associated parameters such as storage size 1398 and retention policies. 1400 When specifying the task to execute within the Schedule, i.e., 1401 creating an Action, it is possible to add to the task configuration 1402 option parameters. This allows the Task Configuration to determine 1403 the common characteristics of a Task, while selected parameters 1404 (e.g., the test target URL) are defined within the schedule. A 1405 single Tasks Configuration can even be used multiple times in the 1406 same schedule with different additional parameters. This allows for 1407 efficiency in creating and transferring the Instruction. Note that 1408 the semantics of what happens if an option is defined multiple times 1409 (either in the Task Configuration, Schedule or in both) is not 1410 standardised and will depend upon the Task. For example, some tasks 1411 may legitimately take multiple values for a single parameter. 1413 Where Options are specified in both the Schedule and the Task 1414 Configuration, the Schedule Options are appended to those specified 1415 in the Task Configuration. 1417 Example: An Action of a Schedule references a single Measurement 1418 Task Configuration for measuring UDP latency. It specifies that 1419 results are to be sent to a Schedule with a Reporting Action. 1420 This Reporting Task of the Reporting Action is executed by a 1421 separate Schedule that specifies that it should run hourly at 5 1422 minutes past the hour. When run this Reporting Action takes the 1423 data generated by the UDP latency Measurement Task as well as any 1424 other data to be included in the hourly report and transfers it to 1425 the Collector over the Report Channel specified within its own 1426 Schedule. 1428 3.7.1. Definition of ma-schedule-obj 1430 object { 1431 string ma-schedule-name; 1432 ma-event-obj ma-schedule-start; 1433 [ma-event-obj ma-schedule-end;] 1434 [int ma-schedule-duration;] 1435 ma-action-obj ma-schedule-actions<0..*>; 1436 string ma-schedule-execution-mode; 1437 [string ma-schedule-tags<0..*>;] 1438 [string ma-schedule-suppression-tags<0..*>;] 1439 } ma-schedule-obj; 1441 The ma-schedule-obj is the main scheduling object. It consists of 1442 the following elements: 1444 ma-schedule-name: A name uniquely identifying a 1445 scheduling object. 1447 ma-schedule-start: An event object indicating when the 1448 schedule starts. 1450 ma-schedule-end: An optional event object controlling 1451 the forceful termination of scheduled 1452 actions. When the event occurs, all 1453 actions of the schedule will be forced 1454 to terminate gracefully. 1456 ma-schedule-duration: An optional duration in seconds for the 1457 schedule. All actions of the schedule 1458 will be forced to terminate gracefully 1459 after the duration number of seconds 1460 past the start of the schedule. 1462 ma-schedule-actions: A possibly empty ordered list of 1463 actions to invoke when the schedule 1464 starts. 1466 ma-schedule-execution-mode: Indicates whether the actions should be 1467 executed sequentially, in parallel, or 1468 in a pipelined mode (where data 1469 produced by one action is passed to the 1470 subsequent action). The default 1471 execution mode is pipelined. 1473 ma-schedule-tags: An optional unordered set of tags that 1474 are reported together with the 1475 measurement results to a collector. 1477 ma-schedule-suppression-tags: An optional unordered set of 1478 suppression tags that are used to 1479 select schedules to be suppressed. 1481 3.7.2. Definition of ma-action-obj 1483 object { 1484 string ma-action-name; 1485 string ma-action-config-task-name; 1486 [ma-option-obj ma-action-task-options<0..*>;] 1487 [string ma-action-destinations<0..*>;] 1488 [string ma-action-tags<0..*>;] 1489 [string ma-action-suppression-tags<0..*>;] 1490 } ma-action-obj; 1492 The ma-action-obj models an a task together with its schedule 1493 specific task options and destination tasks. It consists of the 1494 following elements: 1496 ma-action-name: A name uniquely identifying an action 1497 of a scheduling object. 1499 ma-action-config-task-name: A name identifying the configured task 1500 to be invoked by the action. 1502 ma-action-task-options: An optional and possibly empty ordered 1503 list of options (name-value pairs) that 1504 are passed to the task by appending 1505 them to the options configured for the 1506 task object. 1508 ma-action-destinations: An optional and possibly empty 1509 unordered set of names of destination 1510 schedules that consume output produced 1511 by this action. 1513 ma-action-tags: An optional unordered set of tags that 1514 are reported together with the 1515 measurement results to a collector. 1517 ma-action-suppression-tags: An optional unordered set of 1518 suppression tags that are used to 1519 select actions to be suppressed. 1521 3.8. Common Objects: Channels 1523 A Channel defines a bi-directional communication channel between the 1524 MA and a Controller or Collector. Multiple Channels can be defined 1525 to enable results to be split or duplicated across different 1526 Collectors. 1528 Each Channel contains the details of the remote endpoint (including 1529 location and security credential information such as the 1530 certificate). The timing of when to communicate over a Channel is 1531 specified by the Schedule which executes the corresponding Control or 1532 Reporting Task. The certificate can be the digital certificate 1533 associated to the FQDN in the URL or it can be the certificate of the 1534 Certification Authority that was used to issue the certificate for 1535 the FQDN (Fully Qualified Domain Name) of the target URL (which will 1536 be retrieved later on using a communication protocol such as TLS). 1537 In order to establish a secure channel, the MA will use it's own 1538 security credentials (in the Configuration Information) and the given 1539 credentials for the individual Channel end-point. 1541 As with the Task Configurations, each Channel is also given a text 1542 name by which it can be referenced as a Task Option. 1544 Although the same in terms of information, Channels used for 1545 communication with the Controller are referred to as Control Channels 1546 whereas Channels to Collectors are referred to as Report Channels. 1547 Hence Control Channels will be referenced from Control Tasks executed 1548 by a Control Schedule, whereas Report Channels will be referenced 1549 from within Reporting Tasks executed by an Instruction Schedule. 1551 Multiple interfaces are also supported. For example the Reporting 1552 Task could be configured to send some results over GPRS. This is 1553 especially useful when such results indicate the loss of connectivity 1554 on a different network interface. 1556 Example: A Channel used for reporting results may specify that 1557 results are to be sent to the URL (https://collector.example.org/ 1558 report/), using the appropriate digital certificate to establish a 1559 secure channel.. 1561 3.8.1. Definition of ma-channel-obj 1563 object { 1564 string ma-channel-name; 1565 url ma-channel-target; 1566 credentials ma-channel-credentials; 1567 [string ma-channel-interface-name;] 1568 } ma-channel-obj; 1570 The ma-channel-obj consists of the following elements: 1572 ma-channel-name: A unique name identifying the channel 1573 object. 1575 ma-channel-target: A URL identifying the target channel 1576 endpoint. 1578 ma-channel-credentials: The security credentials needed to 1579 establish a secure channel. 1581 ma-channel-interface-name: An optional name of the network interface 1582 to be used. If not present, the system 1583 will select a suitable interface. 1585 3.9. Common Objects: Task Configurations 1587 Conceptually each Task Configuration defines the parameters of a Task 1588 that the Measurement Agent (MA) may perform at some point in time. 1589 It does not by itself actually instruct the MA to perform them at any 1590 particular time (this is done by a Schedule). Tasks can be 1591 Measurement Tasks (i.e., those Tasks actually performing some type of 1592 passive or active measurement) or any other scheduled activity 1593 performed by the MA such as transferring information to or from the 1594 Controller and Collectors. Other examples of Tasks may include data 1595 manipulation or processing Tasks conducted on the MA. 1597 A Measurement Task Configuration is the same in information terms to 1598 any other Task Configuration. Both measurement and non-measurement 1599 Tasks have registry entries to enable the MA to uniquely identify the 1600 Task it should execute and retrieve the schema for any parameters 1601 that may be passed to the Task. Registry entries are specified as a 1602 URI and can therefore be used to identify the Task within a namespace 1603 or point to a web or local file location for the Task information. 1604 As mentioned previously, these URIs may be used to identify the 1605 Measurement Task in a public namespace 1606 [I-D.ietf-ippm-metric-registry]. 1608 Example: A Measurement Task Configuration may configure a single 1609 Measurement Task for measuring UDP latency. The Measurement Task 1610 Configuration could define the destination port and address for 1611 the measurement as well as the duration, internal packet timing 1612 strategy and other parameters (for example a stream for one hour 1613 and sending one packet every 500 ms). It may also define the 1614 output type and possible parameters (for example the output type 1615 can be the 95th percentile mean) where the measurement task 1616 accepts such parameters. It does not define when the task starts 1617 (this is defined by the Schedule element), so it does not by 1618 itself instruct the MA to actually perform this Measurement Task. 1620 The Task Configuration will include a local short name for reference 1621 by a Schedule. Task Configurations may also refer to registry 1622 entries as described above. In addition the Task can be configured 1623 through a set of configuration Options. The nature and number of 1624 these Options will depend upon the Task. These options are expressed 1625 as name-value pairs although the 'value' may be a structured object 1626 instead of a simple string or numeric value. The implementation of 1627 these name-value pairs will vary between data models. 1629 An Option that must be present for Reporting Tasks is the Channel 1630 reference specifying how to communicate with a Collector. This is 1631 included in the task options and will have a value that matches a 1632 channel name that has been defined in the Instruction. Similarly 1633 Control Tasks will have a similar option with the value set to a 1634 specified Control Channel. 1636 A reporting task might also have a flag parameter to indicate whether 1637 to report if there is no measurement result data pending to be 1638 transferred to the Collector. In addition many tasks will also take 1639 as a parameter which interface to operate over. 1641 The Task Configuration also contains a suppress-by-default flag that 1642 specifies the behaviour of a default suppress instruction (that does 1643 not list explicit tasks or schedules). If this flag is set to FALSE 1644 then the Task will not be suppressed. It should be noted that 1645 Controller Tasks are not subject to the suppression instruction and 1646 therefore this flag will be ignored in such cases. 1648 In addition the Task Configuration may optionally also be given tags 1649 that can carry a Measurement Cycle ID. The purpose of this ID is to 1650 easily identify a set of measurement results that have been produced 1651 by Measurement Tasks with comparable Options. This ID could be 1652 manually incremented or otherwise changed when an Option change is 1653 implemented which could mean that two sets of results should not be 1654 directly compared. 1656 3.9.1. Definition of ma-task-obj 1658 object { 1659 string ma-task-name; 1660 ma-metric-registry-obj ma-task-metrics<0..*>; 1661 [ma-option-obj ma-task-options<0..*>;] 1662 [boolean ma-task-suppress-by-default;] 1663 [string ma-task-tags<0..*>;] 1664 } ma-task-obj; 1666 The ma-task-obj defines a configured task that can be invoked as part 1667 of an action. A configured task can be referenced by its name and it 1668 contains a set of URIs to link to a metrics registry or a local 1669 specification of the task. Options allow the configuration of task 1670 parameters (in the form of name-value pairs). The ma-task-obj 1671 consists of the following elements: 1673 ma-task-name: A name uniquely identifying a 1674 configured task object. 1676 ma-task-metrics: A possibly empty unordered set of 1677 registered metrics and associated roles 1678 the configured measurement task will 1679 use. 1681 ma-task-options: An optional and possibly empty ordered 1682 list of options (name-value pairs) that 1683 are passed to the configured task. 1685 ma-task-suppress-by-default: A boolean flag indicating whether this 1686 configured task will be suppressed by 1687 default. The default value of the flag 1688 is true. 1690 ma-task-tags: An optional unordered set of tags that 1691 are reported together with the 1692 measurement results to a collector. 1694 3.9.2. Definition of ma-option-obj 1696 object { 1697 string ma-option-name; 1698 [object ma-option-value;] 1699 } ma-option-obj; 1701 The ma-option-obj models a name-value pair and consists of the 1702 following elements: 1704 ma-option-name: The name of the option. 1706 ma-option-value: The optional value of the option. 1708 While many of the Task Configuration Options are left to individual 1709 tasks to define, some common Options are used by multiple tasks and 1710 benefit from standardisation. These Options are Channel and Role. 1712 o Channel is used to specify the details of an endpoint for Control 1713 or Reporting Task communications and is detailed elsewhere in this 1714 document. The common option name for specifying the channel is 1715 "channel". 1717 o Role is used to specify which Role the task should be performing 1718 (as defined in the registry) if multiple roles are available. The 1719 common option name for specifying the role is "role". 1721 3.10. Common Objects: Registry Information 1723 Tasks and actions can be associated with entries in a metrics 1724 registry. A metric is identified by a URI and a metric may have 1725 associated roles. 1727 3.10.1. Definition of ma-metric-registry-obj 1729 object { 1730 uri ma-metric-registry-entry; 1731 [string ma-metric-registry-role<0..*>;] 1732 } ma-metric-registry-obj; 1734 The ma-metric-registry-obj defines a registered metric and the 1735 associated role(s). The ma-metric-registry-obj consists of the 1736 following elements: 1738 ma-metric-registry-entry: A URI identifying a metric in a metric 1739 registry. 1741 ma-metric-registry-role: An optional and possibly empty unordered 1742 set of roles for the metric. 1744 3.11. Common Objects: Event Information 1746 The Event information object used throughout the information models 1747 can initially take one of five different forms. Additional forms may 1748 be defined later in order to bind the execution of schedules to 1749 additional events. The initially defined five Event forms are: 1751 1. Periodic Timing: Emits multiple events periodically according to 1752 an interval time defined in seconds 1754 2. Calendar Timing: Emits multiple events according to a calendar 1755 based pattern, e.g., 22 minutes past each hour of the day on 1756 weekdays 1758 3. One Off Timing: Emits one event at a specific date and time 1760 4. Immediate: Emits one event as soon as possible 1762 5. Startup: Emits an event whenever the MA is started (e.g., at 1763 device startup) 1765 Optionally each of the Event options may also specify a randomness 1766 that should be evaluated and applied separately to each indicated 1767 event. This randomness parameter defines a uniform interval in 1768 seconds over which the start of the task is delayed from the starting 1769 times specified by the timing object. 1771 Both the Periodic and Calendar timing objects allow for a series of 1772 Actions to be executed. While both have an optional end time, it is 1773 best practice to always configure an end time and refresh the 1774 information periodically to ensure that lost MAs do not continue 1775 their tasks forever. 1777 Startup events are only created on device startup, not when a new 1778 Instruction is transferred to the MA. If scheduled task execution is 1779 desired both on the transfer of the Instruction and on device restart 1780 then both the Immediate and Startup timing needs to be used in 1781 conjunction. 1783 The datetime format used for all elements in the information model 1784 MUST conform to RFC 3339 [RFC3339]. 1786 3.11.1. Definition of ma-event-obj 1788 object { 1789 string ma-event-name; 1790 union { 1791 ma-periodic-obj ma-event-periodic; 1792 ma-calendar-obj ma-event-calendar; 1793 ma-one-off-obj ma-event-one-off; 1794 ma-immediate-obj ma-event-immediate; 1795 ma-startup-obj ma-event-startup; 1796 ma-immediate-obj ma-event-immediate; 1797 ma-startup-obj ma-event-startup; 1798 ma-controller-lost-obj ma-event-controller-lost; 1799 ma-controller-connected-obj ma-event-controller-connected; 1800 } 1801 [int ma-event-random-spread;] 1802 } ma-event-obj; 1804 The ma-event-obj is the main event object. Event objects are 1805 identified by a name. A generic event object itself contains a more 1806 specific event object. The set of specific event objects should be 1807 extensible. The initial set of specific event objects is further 1808 described below. The ma-event-obj also includes an optional uniform 1809 random spread that can be used to randomize the start times of 1810 scheduled tasks. The ma-event-obj consists of the following 1811 elements: 1813 ma-event-name: The name uniquely identifies an event 1814 object. Schedules refer to event 1815 objects by this name. 1817 ma-event-periodic: The ma-event-periodic is present for 1818 periodic timing objects. 1820 ma-event-calendar: The ma-event-calendar is present for 1821 calendar timing objects. 1823 ma-event-one-off: The ma-event-one-off is present for 1824 one-off timing objects. 1826 ma-event-immediate: The ma-event-immediate is present for 1827 immediate event objects. 1829 ma-event-startup: The ma-event-startup is present for 1830 startup event objects. 1832 ma-event-controller-lost: The ma-event-controller-lost is 1833 present for connectivity to 1834 controller lost event objects. 1836 ma-event-controller-connected: The ma-event-controller-connected is 1837 present for connectivity to a 1838 controller established event objects. 1840 ma-event-random-spread: The optional ma-event-random-spread 1841 adds a random delay defined in 1842 seconds to the event object. 1844 3.11.2. Definition of ma-periodic-obj 1846 object { 1847 [datetime ma-periodic-start;] 1848 [datetime ma-periodic-end;] 1849 int ma-periodic-interval; 1850 } ma-periodic-obj; 1852 The ma-periodic-obj timing object has an optional start and an 1853 optional end time plus a periodic interval. Schedules using an ma- 1854 periodic-obj are started periodically between the start and end time. 1855 The ma-periodic-obj consists of the following elements: 1857 ma-periodic-start: The optional date and time at which 1858 Schedules using this object are first 1859 started. If not present it defaults to 1860 immediate. 1862 ma-periodic-end: The optional date and time at which 1863 Schedules using this object are last 1864 started. If not present it defaults to 1865 indefinite. 1867 ma-periodic-interval: The interval defines the time in seconds 1868 between two consecutive starts of tasks. 1870 3.11.3. Definition of ma-calendar-obj 1872 Calendar Timing supports the routine execution of Actions at specific 1873 times and/or on specific dates. It can support more flexible timing 1874 than Periodic Timing since the execution of Actions does not have to 1875 be uniformly spaced. For example a Calendar Timing could support the 1876 execution of a Measurement Task every hour between 6pm and midnight 1877 on weekdays only. 1879 Calendar Timing is also required to perform measurements at 1880 meaningful times in relation to network usage (e.g., at peak times). 1881 If the optional timezone offset is not supplied then local system 1882 time is assumed. This is essential in some use cases to ensure 1883 consistent peak-time measurements as well as supporting MA devices 1884 that may be in an unknown timezone or roam between different 1885 timezones (but know their own timezone information such as through 1886 the mobile network). 1888 The calendar elements within the Calendar Timing do not have defaults 1889 in order to avoid accidental high-frequency execution of Tasks. If 1890 all possible values for an element are desired then the wildcard * is 1891 used. 1893 object { 1894 [datetime ma-calendar-start;] 1895 [datetime ma-calendar-end;] 1896 [string ma-calendar-months<0..*>;] 1897 [string ma-calendar-days-of-week<0..*>;] 1898 [string ma-calendar-days-of-month<0..*>;] 1899 [string ma-calendar-hours<0..*>;] 1900 [string ma-calendar-minutes<0..*>;] 1901 [string ma-calendar-seconds<0..*>;] 1902 [int ma-calendar-timezone-offset;] 1903 } ma-calendar-obj; 1905 ma-calendar-start: The optional date and time at which 1906 Schedules using this object are first 1907 started. If not present it defaults to 1908 immediate. 1910 ma-calendar-end: The optional date and time at which 1911 Schedules using this object are last 1912 started. If not present it defaults to 1913 indefinite. 1915 ma-calendar-months: The optional set of months (1-12) on 1916 which tasks scheduled using this object 1917 are started. The wildcard * means all 1918 months. If not present, it defaults to 1919 no months. 1921 ma-calendar-days-of-week: The optional set of days of a week 1922 ("Mon", "Tue", "Wed", "Thu", "Fri", 1923 "Sat", "Sun") on which tasks scheduled 1924 using this object are started. The 1925 wildcard * means all days of the week. 1926 If not present, it defaults to no days. 1928 ma-calendar-days-of-month: The optional set of days of a months 1929 (1-31) on which tasks scheduled using 1930 this object are started. The wildcard 1931 * means all days of a months. If not 1932 present, it defaults to no days. 1934 ma-calendar-hours: The optional set of hours (0-23) on 1935 which tasks scheduled using this object 1936 are started. The wildcard * means all 1937 hours of a day. If not present, it 1938 defaults to no hours. 1940 ma-calendar-minutes: The optional set of minutes (0-59) on 1941 which tasks scheduled using this object 1942 are started. The wildcard * means all 1943 minutes of an hour. If not present, it 1944 defaults to no hours. 1946 ma-calendar-seconds: The optional set of seconds (0-59) on 1947 which tasks scheduled using this object 1948 are started. The wildcard * means all 1949 seconds of an hour. If not present, it 1950 defaults to no seconds. 1952 ma-calendar-timezone-offset: The optional timezone offest in hours. 1953 If not present, it defaults to the 1954 system's local timezone. 1956 If a day of the month is specified that does not exist in the month 1957 (e.g., 29th of Feburary) then those values are ignored. 1959 3.11.4. Definition of ma-one-off-obj 1961 object { 1962 datetime ma-one-off-time; 1963 } ma-one-off-obj; 1965 The ma-one-off-obj timing object specifies a fixed point in time. 1966 Schedules using an ma-one-off-obj are started once at the specified 1967 date and time. The ma-one-off-obj consists of the following 1968 elements: 1970 ma-one-off-time: The date and time at which Schedules using 1971 this object are started. 1973 3.11.5. Definition of ma-immediate-obj 1975 object { 1976 // empty 1977 } ma-immediate-obj; 1979 The ma-immediate-obj event object has no further information 1980 elements. Schedules using an ma-immediate-obj are started as soon as 1981 possible. 1983 3.11.6. Definition of ma-startup-obj 1985 object { 1986 // empty 1987 } ma-startup-obj; 1989 The ma-startup-obj event object has no further information elements. 1990 Schedules or suppressions using an ma-startup-obj are started at MA 1991 initialization time. 1993 3.11.7. Definition of ma-controller-lost-obj 1995 object { 1996 // empty 1997 } ma-controller-lost-obj; 1999 The ma-controller-lost-obj event object has no further information 2000 elements. The ma-controller-lost-obj indicates that connectivity to 2001 the controller has been lost. This is determined by a timer started 2002 after each successful contact with a controller. When the timer 2003 reaches the controller-timeout (measured in seconds), an ma- 2004 controller-lost-obj event is generated. This event may be used to 2005 start a suppression. 2007 3.11.8. Definition of ma-controller-connected-obj 2009 object { 2010 // empty 2011 } ma-controller-connected-obj; 2013 The ma-controller-connected-obj event object has no further 2014 information elements. The ma-controller-connected-obj indicates that 2015 connectivity to the controller has been established again after it 2016 was lost. This event may be used to end a suppression. 2018 4. IANA Considerations 2020 This document makes no request of IANA. 2022 Note to RFC Editor: this section may be removed on publication as an 2023 RFC. 2025 5. Security Considerations 2027 This Information Model deals with information about the control and 2028 reporting of the Measurement Agent. There are broadly two security 2029 considerations for such an Information Model. Firstly the 2030 Information Model has to be sufficient to establish secure 2031 communication channels to the Controller and Collector such that 2032 other information can be sent and received securely. Additionally, 2033 any mechanisms that the Network Operator or other device 2034 administrator employs to pre-configure the MA must also be secure to 2035 protect unauthorized parties from modifying pre-configuration 2036 information. These mechanisms are important to ensure that the MA 2037 cannot be hijacked, for example to participate in a DDoS attack. 2039 The second consideration is that no mandated information items should 2040 pose a risk to confidentiality or privacy given such secure 2041 communication channels. For this latter reason items such as the MA 2042 context and MA ID are left optional and can be excluded from some 2043 deployments. This would, for example, allow the MA to remain 2044 anonymous and for information about location or other context that 2045 might be used to identify or track the MA to be omitted or blurred. 2047 The Information Model should support wherever relevant, all the 2048 security and privacy requirements associated with the LMAP Framework. 2050 6. Acknowledgements 2052 The notation was inspired by the notation used in the ALTO protocol 2053 specification. 2055 Philip Eardley, Trevor Burbridge, Marcelo Bagnulo and Juergen 2056 Schoenwaelder worked in part on the Leone research project, which 2057 received funding from the European Union Seventh Framework Programme 2058 [FP7/2007-2013] under grant agreement number 317647. 2060 Juergen Schoenwaelder was partly funded by Flamingo, a Network of 2061 Excellence project (ICT-318488) supported by the European Commission 2062 under its Seventh Framework Programme. 2064 7. References 2066 7.1. Normative References 2068 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2069 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 2070 RFC2119, March 1997, 2071 . 2073 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 2074 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 2075 . 2077 [RFC7594] Eardley, P., Morton, A., Bagnulo, M., Burbridge, T., 2078 Aitken, P., and A. Akhter, "A Framework for Large-Scale 2079 Measurement of Broadband Performance (LMAP)", RFC 7594, 2080 DOI 10.17487/RFC7594, September 2015, 2081 . 2083 7.2. Informative References 2085 [I-D.ietf-ippm-metric-registry] 2086 Bagnulo, M., Claise, B., Eardley, P., Morton, A., and A. 2087 Akhter, "Registry for Performance Metrics", draft-ietf- 2088 ippm-metric-registry-05 (work in progress), October 2015. 2090 [I-D.ietf-lmap-yang] 2091 Schoenwaelder, J. and V. Bajpai, "A YANG Data Model for 2092 LMAP Measurement Agents", draft-ietf-lmap-yang-03 (work in 2093 progress), March 2016. 2095 [RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between 2096 Information Models and Data Models", RFC 3444, DOI 10 2097 .17487/RFC3444, January 2003, 2098 . 2100 [RFC7398] Bagnulo, M., Burbridge, T., Crawford, S., Eardley, P., and 2101 A. Morton, "A Reference Path and Measurement Points for 2102 Large-Scale Measurement of Broadband Performance", RFC 2103 7398, DOI 10.17487/RFC7398, February 2015, 2104 . 2106 Appendix A. Open Issues 2108 A.1. Remove suppress-by-default 2110 The text states already that suppress-by-default (which defaults to 2111 'true') only applies to measurement tasks but not to control tasks. 2112 Hence, a default suppression by default suppresses all non-control 2113 tasks. The proposal is to simply hardwire this. If other sets of 2114 suppression tasks are needed, we should use the tagging mechanism to 2115 define these sets. Having two mechanisms to define set of things to 2116 suppress seems more complex than needed. Proposal: Remove suppress- 2117 by-default and state that default suppression affects all non-control 2118 tasks. More specific suppressions can be configured using tags. 2120 A.2. Overlapping schedules/actions are skipped 2122 Add text that says the execution of actions or schedules is skipped 2123 if previous invocations are still running. We already have counters 2124 for this but there probably needs to be some additional text to go 2125 somewhere. 2127 A.3. Storage usage reporting and control 2129 Actions that feed results into other schedules occupy storage space. 2130 The proposal is to at least report how much storage is allocated to 2131 schedules and actions. Ideally, there would also be controls that 2132 can disable schedules or actions (or through events to start specific 2133 suppressions) if storage is getting tight. Or there should be a 2134 threshold that once crossed causes old data to be deleted. Anything 2135 more reasonable than simply failing once storage has been exhausted. 2137 A.4. Configuration vs. instruction: ma-task-obj 2139 It seems that ma-task-obj should only be configured by a system that 2140 has the access rights to setup the measurement agent. The controller 2141 should read the configured tasks and then only install schedules 2142 (with actions), suppressions, and events. That is, changing ma-task- 2143 obj is not part of an instruction but only part of the configuration. 2145 A.5. Streamline the reporting model 2147 The reporting model may need more attention; perhaps things can be 2148 streamlined and also be made more efficient. Implementation 2149 experience will help to work this out. 2151 Appendix B. Non-editorial Changes since -08 2153 o Refactored the ma-report-task-obj into the ma-report-result-obj. 2155 o Introduced the ma-report-table-obj so that a result can contain 2156 multiple tables. 2158 o Report schedule, action, and task name as part of the ma-report- 2159 result-obj. 2161 o Report conflicts per ma-report-result-obj and not per ma-report- 2162 row-obj. 2164 o Report the start/end time as part of the ma-report-result-obj. 2166 Appendix C. Non-editorial Changes since -07 2168 o Added ma-schedule-end and ma-schedule-duration. 2170 o Changed the granularity of scheduler timings to seconds. 2172 o Added ma-status-suppression-obj to report the status of 2173 suppressions as done in the YANG data model. 2175 o Added counters to schedule and action status objects to match the 2176 counters in the YANG data model. 2178 o Using tags to pass information such as a measurement cycle 2179 identifier to the collector. 2181 o Using suppression tags and glob-style matching to select schedules 2182 and actions to be suppressed. 2184 Appendix D. Non-editorial Changes since -06 2186 o The default execution mode is pipelined (LI12) 2188 o Added text to define which action consumes data in sequential, 2189 pipelines, and parallel execution mode (LI11) 2191 o Added ma-config-measurement-point, ma-report-measurement-point, 2192 and ma-config-report-measurement-point to configure and report the 2193 measurement point (LI10) 2195 o Turned ma-suppression-obj into a list that uses a start event and 2196 a stop event to define the start and end of suppression; this 2197 unifies the handling of suppression and loss of controller 2198 connectivity (LI09) 2200 o Added ma-controller-lost-obj and ma-controller-ok-obj event 2201 objects (LI09) 2203 o Added ma-status-schedule-obj to report the status of a schedule 2204 and refactored ma-task-status-obj into ma-status-action-obj to 2205 report the status of an action (LI07, LI08) 2207 o Introduced a common ma-metric-registry-obj that identifies a 2208 metric and a set of associated roles and added this object to 2209 expose metric capabilities and to support the configuration of 2210 metrics and to report the metrics used (LI06) 2212 o Introduced ma-capability-obj and ma-capability-task-obj to expose 2213 the capabilities of a measurement agent (LI05) 2215 o Use 'ordered list' or 'unordered set' instead of list, collection, 2216 etc. (LI02) 2218 o Clarification that Actions are part of a Schedule (LI03) 2220 o Deleted terms that are not strictly needed (LI04) 2222 Appendix E. Non-editorial Changes since -05 2224 o A task can now reference multiply registry entries. 2226 o Consistent usage of the term Action and Task. 2228 o Schedules are triggered by Events instead of Timings; Timings are 2229 just one of many possible event sources. 2231 o Actions feed into other Schedules (instead of Actions within other 2232 Schedules). 2234 o Removed the notion of multiple task outputs. 2236 o Support for sequential, parallel, and pipelined execution of 2237 Actions. 2239 Authors' Addresses 2241 Trevor Burbridge 2242 BT 2243 Adastral Park, Martlesham Heath 2244 Ipswich IP5 3RE 2245 United Kingdom 2247 Email: trevor.burbridge@bt.com 2248 Philip Eardley 2249 BT 2250 Adastral Park, Martlesham Heath 2251 Ipswich IP5 3RE 2252 United Kingdom 2254 Email: philip.eardley@bt.com 2256 Marcelo Bagnulo 2257 Universidad Carlos III de Madrid 2258 Av. Universidad 30 2259 Leganes, Madrid 28911 2260 Spain 2262 Email: marcelo@it.uc3m.es 2264 Juergen Schoenwaelder 2265 Jacobs University Bremen 2266 Campus Ring 1 2267 Bremen 28759 2268 Germany 2270 Email: j.schoenwaelder@jacobs-university.de