idnits 2.17.1 draft-ietf-lmap-information-model-16.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 705 has weird spacing: '...ion-obj ma-in...' == Line 894 has weird spacing: '...ask-obj ma-ca...' == Line 940 has weird spacing: '...ace-obj ma-...' == Line 942 has weird spacing: '...ion-obj ma-st...' == Line 976 has weird spacing: '...ion-obj ma-...' == (7 more instances...) -- The document date (January 13, 2017) is 2659 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-24) exists of draft-ietf-ippm-metric-registry-10 == Outdated reference: A later version (-12) exists of draft-ietf-lmap-yang-08 Summary: 0 errors (**), 0 flaws (~~), 10 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Burbridge 3 Internet-Draft P. Eardley 4 Intended status: Standards Track BT 5 Expires: July 17, 2017 M. Bagnulo 6 Universidad Carlos III de Madrid 7 J. Schoenwaelder 8 Jacobs University Bremen 9 January 13, 2017 11 Information Model for Large-Scale Measurement Platforms (LMAP) 12 draft-ietf-lmap-information-model-16 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 July 17, 2017. 48 Copyright Notice 50 Copyright (c) 2017 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents 55 (http://trustee.ietf.org/license-info) in effect on the date of 56 publication of this document. Please review these documents 57 carefully, as they describe your rights and restrictions with respect 58 to this document. Code Components extracted from this document must 59 include Simplified BSD License text as described in Section 4.e of 60 the Trust Legal Provisions and are provided without warranty as 61 described in the Simplified BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 66 2. Notation . . . . . . . . . . . . . . . . . . . . . . . . . . 5 67 3. LMAP Information Model . . . . . . . . . . . . . . . . . . . 5 68 3.1. Pre-Configuration Information . . . . . . . . . . . . . . 9 69 3.1.1. Definition of ma-preconfig-obj . . . . . . . . . . . 10 70 3.2. Configuration Information . . . . . . . . . . . . . . . . 10 71 3.2.1. Definition of ma-config-obj . . . . . . . . . . . . . 12 72 3.3. Instruction Information . . . . . . . . . . . . . . . . . 13 73 3.3.1. Definition of ma-instruction-obj . . . . . . . . . . 15 74 3.3.2. Definition of ma-suppression-obj . . . . . . . . . . 16 75 3.4. Logging Information . . . . . . . . . . . . . . . . . . . 17 76 3.4.1. Definition of ma-log-obj . . . . . . . . . . . . . . 19 77 3.5. Capability and Status Information . . . . . . . . . . . . 19 78 3.5.1. Definition of ma-capability-obj . . . . . . . . . . . 19 79 3.5.2. Definition of ma-capability-task-obj . . . . . . . . 20 80 3.5.3. Definition of ma-status-obj . . . . . . . . . . . . . 20 81 3.5.4. Definition of ma-status-schedule-obj . . . . . . . . 21 82 3.5.5. Definition of ma-status-action-obj . . . . . . . . . 22 83 3.5.6. Definition of ma-status-suppression-obj . . . . . . . 25 84 3.5.7. Definition of ma-status-interface-obj . . . . . . . . 25 85 3.6. Reporting Information . . . . . . . . . . . . . . . . . . 26 86 3.6.1. Definition of ma-report-obj . . . . . . . . . . . . . 28 87 3.6.2. Definition of ma-report-result-obj . . . . . . . . . 28 88 3.6.3. Definition of ma-report-conflict-obj . . . . . . . . 30 89 3.6.4. Definition of ma-report-table-obj . . . . . . . . . . 31 90 3.6.5. Definition of ma-report-row-obj . . . . . . . . . . . 31 91 3.7. Common Objects: Schedules . . . . . . . . . . . . . . . . 31 92 3.7.1. Definition of ma-schedule-obj . . . . . . . . . . . . 33 93 3.7.2. Definition of ma-action-obj . . . . . . . . . . . . . 34 94 3.8. Common Objects: Channels . . . . . . . . . . . . . . . . 35 95 3.8.1. Definition of ma-channel-obj . . . . . . . . . . . . 36 97 3.9. Common Objects: Task Configurations . . . . . . . . . . . 36 98 3.9.1. Definition of ma-task-obj . . . . . . . . . . . . . . 38 99 3.9.2. Definition of ma-option-obj . . . . . . . . . . . . . 38 100 3.10. Common Objects: Registry Information . . . . . . . . . . 39 101 3.10.1. Definition of ma-registry-obj . . . . . . . . . . . 39 102 3.11. Common Objects: Event Information . . . . . . . . . . . . 39 103 3.11.1. Definition of ma-event-obj . . . . . . . . . . . . . 40 104 3.11.2. Definition of ma-periodic-obj . . . . . . . . . . . 42 105 3.11.3. Definition of ma-calendar-obj . . . . . . . . . . . 42 106 3.11.4. Definition of ma-one-off-obj . . . . . . . . . . . . 44 107 3.11.5. Definition of ma-immediate-obj . . . . . . . . . . . 45 108 3.11.6. Definition of ma-startup-obj . . . . . . . . . . . . 45 109 3.11.7. Definition of ma-controller-lost-obj . . . . . . . . 45 110 3.11.8. Definition of ma-controller-connected-obj . . . . . 45 111 4. Example Execution . . . . . . . . . . . . . . . . . . . . . . 46 112 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47 113 6. Security Considerations . . . . . . . . . . . . . . . . . . . 48 114 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 48 115 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 49 116 8.1. Normative References . . . . . . . . . . . . . . . . . . 49 117 8.2. Informative References . . . . . . . . . . . . . . . . . 49 118 Appendix A. Change History . . . . . . . . . . . . . . . . . . . 49 119 A.1. Non-editorial changes since -15 . . . . . . . . . . . . . 50 120 A.2. Non-editorial changes since -14 . . . . . . . . . . . . . 50 121 A.3. Non-editorial changes since -13 . . . . . . . . . . . . . 50 122 A.4. Non-editorial changes since -12 . . . . . . . . . . . . . 50 123 A.5. Non-editorial changes since -11 . . . . . . . . . . . . . 50 124 A.6. Non-editorial changes since -10 . . . . . . . . . . . . . 50 125 A.7. Non-editorial changes since -09 . . . . . . . . . . . . . 50 126 A.8. Non-editorial changes since -08 . . . . . . . . . . . . . 51 127 A.9. Non-editorial changes since -07 . . . . . . . . . . . . . 51 128 A.10. Non-editorial changes since -06 . . . . . . . . . . . . . 51 129 A.11. Non-editorial changes since -05 . . . . . . . . . . . . . 52 130 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 53 132 1. Introduction 134 A large-scale measurement platform is a collection of components that 135 work in a coordinated fashion to perform measurements from a large 136 number of vantage points. The main components of a large-scale 137 measurement platform are the Measurement Agents (hereafter MAs), the 138 Controller(s) and the Collector(s). 140 The MAs are the elements actually performing the measurements. The 141 MAs are controlled by exactly one Controller at a time and the 142 Collectors gather the results generated by the MAs. In a nutshell, 143 the normal operation of a large-scale measurement platform starts 144 with the Controller instructing a set of one or more MAs to perform a 145 set of one or more Measurement Tasks at a certain point in time. The 146 MAs execute the instructions from a Controller, and once they have 147 done so, they report the results of the measurements to one or more 148 Collectors. The overall framework for a Large Measurement platform 149 as used in this document is described in detail in [RFC7594]. 151 A large-scale measurement platform involves basically three types of 152 protocols, namely, a Control protocol (or protocols) between a 153 Controller and the MAs, a Report protocol (or protocols) between the 154 MAs and the Collector(s) and several measurement protocols between 155 the MAs and Measurement Peers (MPs), used to actually perform the 156 measurements. In addition some information is required to be 157 configured on the MA prior to any communication with a Controller. 159 This document defines the information model for both Control and the 160 Report protocols along with pre-configuration information that is 161 required on the MA before communicating with the Controller, broadly 162 named as the LMAP Information Model. The measurement protocols are 163 out of the scope of this document. 165 As defined in [RFC3444], the LMAP Information Model defines the 166 concepts involved in a large-scale measurement platform at a high 167 level of abstraction, independent of any specific implementation or 168 actual protocol used to exchange the information. It is expected 169 that the proposed information model can be used with different 170 protocols in different measurement platform architectures and across 171 different types of MA devices (e.g., home gateway, smartphone, PC, 172 router). A YANG data model implementing the information model can be 173 found in [I-D.ietf-lmap-yang]. 175 The definition of an Information Model serves a number of purposes: 177 1. To guide the standardisation of one or more Control and Report 178 protocols and data models 180 2. To enable high-level inter-operability between different Control 181 and Report protocols by facilitating translation between their 182 respective data models such that a Controller could instruct sub- 183 populations of MAs using different protocols 185 3. To form agreement of what information needs to be held by an MA 186 and passed over the Control and Report interfaces and support the 187 functionality described in the LMAP framework 189 4. To enable existing protocols and data models to be assessed for 190 their suitability as part of a large-scale measurement system 192 2. Notation 194 This document uses a programming language-like notation to define the 195 properties of the objects of the information model. An optional 196 property is enclosed by square brackets, [ ], and a list property is 197 indicated by two numbers in angle brackets, , where m indicates 198 the minimal number of values, and n is the maximum. The symbol * for 199 n means no upper bound. 201 3. LMAP Information Model 203 The information described herein relates to the information stored, 204 received or transmitted by a Measurement Agent as described within 205 the LMAP framework [RFC7594]. As such, some subsets of this 206 information model are applicable to the measurement Controller, 207 Collector and any device management system that pre-configures the 208 Measurement Agent. The information described in these models will be 209 transmitted by protocols using interfaces between the Measurement 210 Agent and such systems according to a Data Model. 212 For clarity the information model is divided into six sections: 214 1. Pre-Configuration Information. Information pre-configured on the 215 Measurement Agent prior to any communication with other 216 components of the LMAP architecture (i.e., the Controller, 217 Collector and Measurement Peers), specifically detailing how to 218 communicate with a Controller and whether the device is enabled 219 to participate as an MA. 221 2. Configuration Information. Update of the pre-configuration 222 information during the registration of the MA or subsequent 223 communication with the Controller, along with the configuration 224 of further parameters about the MA (rather than the Measurement 225 Tasks it should perform) that were not mandatory for the initial 226 communication between the MA and a Controller. 228 3. Instruction Information. Information that is received by the MA 229 from the Controller pertaining to the Measurement Tasks that 230 should be executed. This includes the task execution Schedules 231 (other than the Controller communication Schedule supplied as 232 (pre)configuration information) and related information such as 233 the Task Configuration, communication Channels to Collectors and 234 schedule Event and Timing information. It also includes Task 235 Suppression information that is used to over-ride normal Task 236 execution. 238 4. Logging Information. Information transmitted from the MA to the 239 Controller detailing the results of any configuration operations 240 along with error and status information from the operation of the 241 MA. 243 5. Capability and Status Information. Information on the general 244 status and capabilities of the MA. For example, the set of 245 measurements that are supported on the device. 247 6. Reporting Information. Information transmitted from the MA to 248 one or more Collectors including measurement results and the 249 context in which they were conducted. 251 In addition the MA may hold further information not described herein, 252 and which may be optionally transferred to or from other systems 253 including the Controller and Collector. One example of information 254 in this category is subscriber or line information that may be 255 extracted by a task and reported by the MA in the reporting 256 communication to a Collector. 258 It should also be noted that the MA may be in communication with 259 other management systems which may be responsible for configuring and 260 retrieving information from the MA device. Such systems, where 261 available, can perform an important role in transferring the pre- 262 configuration information to the MA or enabling/disabling the 263 measurement functionality of the MA. 265 The Information Model is divided into sub-sections for a number of 266 reasons. Firstly the grouping of information facilitates reader 267 understanding. Secondly, the particular groupings chosen are 268 expected to map to different protocols or different transmissions 269 within those protocols. 271 The granularity of data transmitted in each operation of the Control 272 and Report Protocols is not dictated by the Information Model. For 273 example, the Instruction object may be delivered in a single 274 operation. Alternatively, Schedules and Task Configurations may be 275 separated or even each Schedule/Task Configuration may be delivered 276 individually. Similarly the Information Model does not dictate 277 whether data is read, write, or read/write. For example, some 278 Control Protocols may have the ability to read back Configuration and 279 Instruction information which have been previously set on the MA. 280 Lastly, while some protocols may simply overwrite information (for 281 example refreshing the entire Instruction Information), other 282 protocols may have the ability to update or delete selected items of 283 information. 285 The information in these six sections is captured by a number of 286 common information objects. These objects are also described later 287 in this document and comprise of: 289 1. Schedules. A set of Schedules tells the MA to do something. 290 Without a Schedule no Task (from a measurement to reporting or 291 communicating with the Controller) is ever executed. Schedules 292 are used within the Instruction to specify what tasks should be 293 performed, when, and how to direct their results. A Schedule is 294 also used within the pre-Configuration and Configuration 295 information in order to execute the Task or Tasks required to 296 communicate with the Controller. A specific Schedule can only be 297 active once. Attempts to start a Schedule while the same 298 Schedule is still running will fail. 300 2. Channels. A set of Channel objects are used to communicate with 301 a number of endpoints (i.e., the Controller and Collectors). 302 Each Channel object contains the information required for the 303 communication with a single endpoint such as the target location 304 and security details. 306 3. Task Configurations. A set of Task Configurations is used to 307 configure the Tasks that are run by the MA. This includes the 308 registry entries for the Task and any configuration parameters, 309 represented as Task Options. Task Configurations are referenced 310 from a Schedule in order to specify what Tasks the MA should 311 execute. 313 4. Events. A set of Event objects that can be referenced from the 314 Schedules. Each Schedule always references exactly one Event 315 object that determines when the schedule is executed. An Event 316 object specifies either a singleton or series of events that 317 indicate when Tasks should be executed. A commonly used kind of 318 Event objects are Timing objects. 320 Figure 1 illustrates the structure in which these common information 321 objects are referenced. The references are achieved by each object 322 (Task Configuration, Event) being given a short textual name that is 323 used by other objects. The objects shown in parenthesis are part of 324 the internal object structure of a Schedule. Channels are not shown 325 in the diagram since they are only used as an option by selected Task 326 Configurations but are similarly referenced using a short text name. 328 Schedule 329 |-- triggered by --> Event 330 | 331 |-- executes --> Action 1 332 | |-- using --> Task Configuration 333 | | 334 | `-- feeding to --> Destination Schedule 335 : 336 : 337 `-- executes --> Action N 338 |-- using --> Task Configuration 339 | 340 `-- feeding to --> Destination Schedule 342 Figure 1: Relationship between Schedules, Events, Actions, Task 343 Configurations, and Destination Schedules 345 The primary function of an MA is to execute Schedules. Every Action 346 contained in a Schedule is defined as a Task. As such, these Actions 347 are configured through Task Configurations and executed according to 348 the Event object referenced by the Schedule in which they appear. 349 Note, however, that Actions can have Action specific parameters. 351 Tasks can implement a variety of different types of Actions. While 352 in terms of the Information Model, all Tasks have the same structure, 353 it can help conceptually to think of different Task categories: 355 1. Measurement Tasks measure some aspect of network performance or 356 traffic. They may also capture contextual information from the 357 MA device or network interfaces such as the device type or 358 interface speed. 360 2. Data Transfer Tasks support the communication with a Controller 361 and Collectors: 363 A. Reporting Tasks report the results of Measurement Tasks to 364 Collectors 366 B. Control Task(s) implement the Control Protocol and 367 communicate with the Controller. 369 3. Data Analysis Tasks can exist to analyse data from other 370 Measurement Tasks locally on the MA 372 4. Data Management Tasks may exist to clean-up, filter or compress 373 data on the MA such as Measurement Task results 375 Figure 1 indicates that Actions can produce data that is fed into 376 Destination Schedules. This can by used by Actions implementing 377 Measurement Tasks to feed measurement results to a Schedule that 378 triggers Actions implementing Reporting Tasks. Data fed to a 379 Destination Schedule is consumed by the first Action of the 380 Destination Schedule if the Destination Schedule is using sequential 381 or pipelined execution mode and it is consumed by all Actions of the 382 Destination Schedule if the Destination Schedule is using parallel 383 execution mode. 385 3.1. Pre-Configuration Information 387 This information is the minimal information that needs to be pre- 388 configured to the MA in order for it to successfully communicate with 389 a Controller during the registration process. Some of the Pre- 390 Configuration Information elements are repeated in the Configuration 391 Information in order to allow an LMAP Controller to update these 392 items. The pre-configuration information also contains some elements 393 that are not under the control of the LMAP framework (such as the 394 device identifier and device security credentials). 396 This Pre-Configuration Information needs to include a URL of the 397 initial Controller from where configuration information can be 398 communicated along with the security information required for the 399 communication including the certificate of the Controller (or the 400 certificate of the Certification Authority which was used to issue 401 the certificate for the Controller). All this is expressed as a 402 Channel. While multiple Channels may be provided in the Pre- 403 Configuration Information they must all be associated with a single 404 Controller (e.g., over different interfaces or network protocols). 406 Where the MA pulls information from the Controller, the Pre- 407 Configuration Information also needs to contain the timing of the 408 communication with the Controller as well as the nature of the 409 communication itself (such as the protocol and data to be 410 transferred). The timing is represented as an Event that invokes a 411 Schedule that executes the Task(s) responsible for communication with 412 the Controller. It is this Task (or Tasks) that implement the 413 Control protocol between the MA and the Controller and utilises the 414 Channel information. The Task(s) may take additional parameters, as 415 defined by a Task Configuration. 417 Even where information is pushed to the MA from the Controller 418 (rather than pulled by the MA), a Schedule still needs to be 419 supplied. In this case the Schedule will simply execute a Controller 420 listener Task when the MA is started. A Channel is still required 421 for the MA to establish secure communication with the Controller. 423 It can be seen that these Channels, Schedules and Task Configurations 424 for the initial MA-Controller communication are no different in terms 425 of the Information Model to any other Channel, Schedule or Task 426 Configuration that might execute a Measurement Task or report the 427 measurement results (as described later). 429 The MA may be pre-configured with an MA ID, or may use a Device ID in 430 the first Controller contact before it is assigned an MA ID. The 431 Device ID may be a MAC address or some other device identifier 432 expressed as a URI. If the MA ID is not provided at this stage then 433 it must be provided by the Controller during Configuration. 435 3.1.1. Definition of ma-preconfig-obj 437 object { 438 [uuid ma-preconfig-agent-id;] 439 ma-task-obj ma-preconfig-control-tasks<1..*>; 440 ma-channel-obj ma-preconfig-control-channels<1..*>; 441 ma-schedule-obj ma-preconfig-control-schedules<1..*>; 442 [uri ma-preconfig-device-id;] 443 credentials ma-preconfig-credentials; 444 } ma-preconfig-obj; 446 The ma-preconfig-obj describes information that needs to be available 447 to the MA in order to bootstrap communication with a Controller. The 448 ma-preconfig-obj consists of the following elements: 450 ma-preconfig-agent-id: An optional uuid uniquely identifying 451 the measurement agent. 453 ma-preconfig-control-tasks: An unordered set of tasks objects. 455 ma-preconfig-control-channels: An unordered set of channel objects. 457 ma-preconfig-control-schedules: An unordered set of scheduling 458 objects. 460 ma-preconfig-device-id: An optional identifier for the 461 device. 463 ma-preconfig-credentials: The security credentials used by the 464 measurement agent. 466 3.2. Configuration Information 468 During registration or at any later point at which the MA contacts 469 the Controller (or vice-versa), the choice of Controller, details for 470 the timing of communication with the Controller or parameters for the 471 communication Task(s) can be changed (as captured by the Channels, 472 Schedules and Task Configurations objects). For example the pre- 473 configured Controller (specified as a Channel or Channels) may be 474 over-ridden with a specific Controller that is more appropriate to 475 the MA device type, location or characteristics of the network (e.g., 476 access technology type or broadband product). The initial 477 communication Schedule may be over-ridden with one more relevant to 478 routine communications between the MA and the Controller. 480 While some Control protocols may only use a single Schedule, other 481 protocols may use several Schedules (and related data transfer Tasks) 482 to update the Configuration Information, transfer the Instruction 483 Information, transfer Capability and Status Information and send 484 other information to the Controller such as log or error 485 notifications. Multiple Channels may be used to communicate with the 486 same Controller over multiple interfaces (e.g., to send logging 487 information over a different network). 489 In addition the MA will be given further items of information that 490 relate specifically to the MA rather than the measurements it is to 491 conduct or how to report results. The assignment of an ID to the MA 492 is mandatory. If the MA Agent ID was not optionally provided during 493 the pre-configuration then one must be provided by the Controller 494 during Configuration. Optionally a Group ID may also be given which 495 identifies a group of interest to which that MA belongs. For example 496 the group could represent an ISP, broadband product, technology, 497 market classification, geographic region, or a combination of 498 multiple such characteristics. Additional flags control whether the 499 MA ID or the Group ID are included in Reports. The reporting of a 500 Group ID without the MA ID allows the MA to remain anonymous, which 501 may be particularly useful to prevent tracking of mobile MA devices. 503 Optionally an MA can also be configured to stop executing any 504 Instruction Schedule if the Controller is unreachable. This can be 505 used as a fail-safe to stop Measurement and other Tasks being 506 conducted when there is doubt that the Instruction Information is 507 still valid. This is simply represented as a time window in seconds 508 since the last communication with the Controller after which an Event 509 is generated that can trigger the suspension of Instruction 510 Schedules. The appropriate value of the time window will depend on 511 the specified communication Schedule with the Controller and the 512 duration for which the system is willing to tolerate continued 513 operation with potentially stale Instruction Information. 515 While Pre-Configuration Information is persistent upon device reset 516 or power cycle, the persistency of the Configuration Information may 517 be device dependent. Some devices may revert back to their pre- 518 configuration state upon reboot or factory reset, while other devices 519 may store all Configuration and Instruction information in persistent 520 storage. A Controller can check whether an MA has the latest 521 Configuration and Instruction information by examining the Capability 522 and Status information for the MA. 524 3.2.1. Definition of ma-config-obj 526 object { 527 uuid ma-config-agent-id; 528 ma-task-obj ma-config-control-tasks<1..*>; 529 ma-channel-obj ma-config-control-channels<1..*>; 530 ma-schedule-obj ma-config-control-schedules<1..*>; 531 credentials ma-config-credentials; 532 [string ma-config-group-id;] 533 [string ma-config-measurement-point;] 534 [boolean ma-config-report-agent-id;] 535 [boolean ma-config-report-group-id;] 536 [boolean ma-config-report-measurement-point;] 537 [int ma-config-controller-timeout;] 538 } ma-config-obj; 540 The ma-config-obj consists of the following elements: 542 ma-config-agent-id: A uuid uniquely identifying the 543 measurement agent. 545 ma-config-control-tasks: An unordered set of task objects. 547 ma-config-control-channels: An unordered set of channel 548 objects. 550 ma-config-control-schedules: An unordered set of scheduling 551 objects. 553 ma-config-credentials: The security credentials used by 554 the measurement agent. 556 ma-config-group-id: An optional identifier of the 557 group of measurement agents this 558 measurement agent belongs to. 560 ma-config-measurement-point: An optional identifier for the 561 measurement point indicating 562 where the measurement agent is 563 located on a path (see [RFC7398] 564 for further details). 566 ma-config-report-agent-id: An optional flag indicating 567 whether the agent identifier (ma- 568 config-agent-id) is included in 569 reports. The default value is 570 true. 572 ma-config-report-group-id: An optional flag indicating 573 whether the group identifier (ma- 574 config-group-id) is included in 575 reports. The default value is 576 false. 578 ma-config-report-measurement-point: An optional flag indicating 579 whether the measurement point 580 (ma-config-measurement-point) 581 should be included in reports. 582 The default value is false. 584 ma-config-controller-timeout: A timer is started after each 585 successful contact with a 586 controller. When the timer 587 reaches the controller-timeout 588 (measured in seconds), an event 589 is raised indicating that 590 connectivity to the controller 591 has been lost (see ma-controller- 592 lost-obj). 594 3.3. Instruction Information 596 The Instruction information model has four sub-elements: 598 1. Instruction Task Configurations 600 2. Report Channels 602 3. Instruction Schedules 604 4. Suppression 606 The Instruction supports the execution of all Tasks on the MA except 607 those that deal with communication with the Controller (specified in 608 (pre-)configuration information). The Tasks are configured in 609 Instruction Task Configurations and included by reference in the 610 Actions of Instruction Schedules that specify when to execute them. 611 The results can be communicated to other Schedules or a Task may 612 implement a Reporting Protocol and communicate results over Report 613 Channels. Suppression is used to temporarily stop the execution of 614 new Tasks as specified by the Instruction Schedules (and optionally 615 to stop ongoing Tasks). 617 A Task Configuration is used to configure the mandatory and optional 618 parameters of a Task. It also serves to instruct the MA about the 619 Task including the ability to resolve the Task to an executable and 620 specifying the schema for the Task parameters. 622 A Report Channel defines how to communicate with a single remote 623 system specified by a URL. A Report Channel is used to send results 624 to a single Collector but is no different in terms of the Information 625 Model to the Control Channel used to transfer information between the 626 MA and the Controller. Several Report Channels can be defined to 627 enable results to be split or duplicated across different 628 destinations. A single Channel can be used by multiple (reporting) 629 Task Configurations to transfer data to the same Collector. A single 630 Reporting Task Configuration can also be included in multiple 631 Schedules. E.g., a single Collector may receive data at three 632 different cycle rates, one Schedule reporting hourly, another 633 reporting daily and a third specifying that results should be sent 634 immediately for on-demand measurement tasks. Alternatively multiple 635 Report Channels can be used to send Measurement Task results to 636 different Collectors. The details of the Channel element is 637 described later as it is common to several objects. 639 Instruction Schedules specify which Actions to execute according to a 640 given triggering Event. An Action is a Task with additional specific 641 parameters. An Event can trigger the execution of a single Action or 642 it can trigger a repeated series of Actions. The Schedule also 643 specifies how to link Tasks output data to other Schedules. 645 Measurement Suppression information is used to over-ride the 646 Instruction Schedule and temporarily stop measurements or other Tasks 647 from running on the MA for a defined or indefinite period. While 648 conceptually measurements can be stopped by simply removing them from 649 the Measurement Schedule, splitting out separate information on 650 Measurement Suppression allows this information to be updated on the 651 MA on a different timing cycle or protocol implementation to the 652 Measurement Schedule. It is also considered that it will be easier 653 for a human operator to implement a temporary explicit suppression 654 rather than having to move to a reduced Schedule and then roll-back 655 at a later time. 657 It should be noted that control schedules and tasks cannot be 658 suppressed as evidenced by the lack of suppression information in the 659 Configuration. The control schedule must only reference tasks listed 660 as control tasks (i.e., within the Configuration information). 662 A single Suppression object is able to enable/disable a set of 663 Instruction Tasks that are tagged for suppression. This enabled fine 664 grained control on which Tasks are suppressed. Suppression of both 665 matching Actions and Measurement Schedules is supported. Support for 666 disabling specific Actions allows malfunctioning or mis-configured 667 Tasks or Actions that have an impact on a particular part of the 668 network infrastructure (e.g., a particular Measurement Peer) to be 669 targeted. Support for disabling specific Schedules allows for 670 particularly heavy cycles or sets of less essential Measurement Tasks 671 to be suppressed quickly and effectively. Note that Suppression has 672 no effect on either Controller Tasks or Controller Schedules. 674 Suppression stops new Tasks from executing. In addition, the 675 Suppression information also supports an additional Boolean that is 676 used to select whether on-going tasks are also to be terminated. 678 Unsuppression is achieved through either overwriting the Measurement 679 Suppression information (e.g., changing 'enabled' to False) or 680 through the use of an End time such that the Measurement Suppression 681 will no longer be in effect beyond this time. The datetime format 682 used for all elements in the information model (e.g., the suppression 683 start and end dates) MUST conform to RFC 3339 [RFC3339]. 685 The goal when defining these four different elements is to allow each 686 part of the information model to change without affecting the other 687 three elements. For example it is envisaged that the Report Channels 688 and the set of Task Configurations will be relatively static. The 689 Instruction Schedule, on the other hand, is likely to be more 690 dynamic, as the measurement panel and test frequency are changed for 691 various business goals. Another example is that measurements can be 692 suppressed with a Suppression command without removing the existing 693 Instruction Schedules that would continue to apply after the 694 Suppression expires or is removed. In terms of the Controller-MA 695 communication this can reduce the data overhead. It also encourages 696 the re-use of the same standard Task Configurations and Reporting 697 Channels to help ensure consistency and reduce errors. 699 3.3.1. Definition of ma-instruction-obj 701 object { 702 ma-task-obj ma-instruction-tasks<0..*>; 703 ma-channel-obj ma-instruction-channels<0..*>; 704 ma-schedule-obj ma-instruction-schedules<0..*>; 705 [ma-suppression-obj ma-instruction-suppressions<0..*>;] 706 } ma-instruction-obj; 708 An ma-instruction-obj consists of the following elements: 710 ma-instruction-tasks: A possibly empty unordered set of task 711 objects. 713 ma-instruction-channels: A possibly empty unordered set of 714 channel objects. 716 ma-instruction-schedules: A possibly empty unordered set of 717 schedule objects. 719 ma-instruction-suppressions: An optional possibly empty unordered 720 set of suppression objects. 722 3.3.2. Definition of ma-suppression-obj 724 object { 725 string ma-suppression-name; 726 [ma-event-obj ma-suppression-start;] 727 [ma-event-obj ma-suppression-end;] 728 [string ma-suppression-match<0..*>;] 729 [boolean ma-suppression-stop-running;] 730 } ma-suppression-obj; 732 The ma-suppression-obj controls the suppression of schedules or 733 actions and consists of the following elements: 735 ma-suppression-name: A name uniquely identifying a 736 suppression. 738 ma-suppression-start: The optional event indicating when 739 suppression starts. If not present, 740 the suppression starts immediately, 741 i.e., as if the value would be 742 'immediate'. 744 ma-suppression-end: The optional event indicating when 745 suppression ends. If not present, the 746 suppression does not have a defined 747 end, i.e., the suppression remains for 748 an indefinite period of time. 750 ma-suppression-match: An optional and possibly empty 751 unordered set of match patterns. The 752 suppression will apply to all schedules 753 (and their actions) that have a 754 matching value in their ma-schedule- 755 suppression-tags and all actions that 756 have a matching value in their ma- 757 action-suppression-tags. Pattern 758 matching is done using glob style 759 pattern (see below). 761 ma-suppression-stop-running: An optional boolean indicating whether 762 suppression will stop any running 763 matching schedules or actions. The 764 default value for this boolean is 765 false. 767 Glob style pattern matching is following POSIX.2 fnmatch() without 768 special treatment of file paths: 770 * matches a sequence of characters 771 ? matches a single character 772 [seq] matches any character in seq 773 [!seq] matches any character not in seq 775 A backslash followed by a character matches the following character. 776 In particular: 778 \* matches * 779 \? matches ? 780 \\ matches \ 782 A sequence seq may be a sequence of characters (e.g., [abc] or a 783 range of characters (e.g., [a-c]). 785 3.4. Logging Information 787 The MA may report on the success or failure of Configuration or 788 Instruction communications from the Controller. In addition further 789 operational logs may be produced during the operation of the MA and 790 updates to capabilities may also be reported. Reporting this 791 information is achieved in exactly the same manner as scheduling any 792 other Task. We make no distinction between a Measurement Task 793 conducting an active or passive network measurement and one which 794 solely retrieves static or dynamic information from the MA such as 795 capabilities or logging information. One or more logging tasks can 796 be programmed or configured to capture subsets of the Logging 797 Information. These logging tasks are then executed by Schedules 798 which also specify that the resultant data is to be transferred over 799 the Controller Channels. 801 The type of Logging Information will fall into three different 802 categories: 804 1. Success/failure/warning messages in response to information 805 updates from the Controller. Failure messages could be produced 806 due to some inability to receive or parse the Controller 807 communication, or if the MA is not able to act as instructed. 808 For example: 810 * "Measurement Schedules updated OK" 812 * "Unable to parse JSON" 814 * "Missing mandatory element: Measurement Timing" 816 * "'Start' does not conform to schema - expected datetime" 818 * "Date specified is in the past" 820 * "'Hour' must be in the range 1..24" 822 * "Schedule A refers to non-existent Measurement Task 823 Configuration" 825 * "Measurement Task Configuration X registry entry Y not found" 827 * "Updated Measurement Task Configurations do not include M used 828 by Measurement Schedule N" 830 2. Operational updates from the MA. For example: 832 * "Out of memory: cannot record result" 834 * "Collector 'collector.example.com' not responding" 836 * "Unexpected restart" 838 * "Suppression timeout" 840 * "Failed to execute Measurement Task Configuration H" 842 3. Status updates from the MA. For example: 844 * "Device interface added: eth3" 846 * "Supported measurements updated" 848 * "New IP address on eth0: xxx.xxx.xxx.xxx" 850 This Information Model document does not detail the precise format of 851 logging information since it is to a large extent protocol and MA 852 specific. However, some common information can be identified. 854 3.4.1. Definition of ma-log-obj 856 object { 857 uuid ma-log-agent-id; 858 datetime ma-log-event-time; 859 code ma-log-code; 860 string ma-log-description; 861 } ma-log-obj; 863 The ma-log-obj models the generic aspects of a logging object and 864 consists of the following elements: 866 ma-log-agent-id: A uuid uniquely identifying the measurement 867 agent. 869 ma-log-event-time: The date and time of the event reported in 870 the logging object. 872 ma-log-code: A machine readable code describing the 873 event. 875 ma-log-description: A human readable description of the event. 877 3.5. Capability and Status Information 879 The MA will hold Capability Information that can be retrieved by a 880 Controller. Capabilities include the device interface details 881 available to Measurement Tasks as well as the set of Measurement 882 Tasks/Roles (specified by registry entries) that are actually 883 installed or available on the MA. Status information includes the 884 times that operations were last performed such as contacting the 885 Controller or producing Reports. 887 3.5.1. Definition of ma-capability-obj 889 object { 890 string ma-capability-hardware; 891 string ma-capability-firmware; 892 string ma-capability-version; 893 [string ma-capability-tags<0..*>;] 894 [ma-capability-task-obj ma-capability-tasks<0..*>;] 895 } ma-capability-obj; 897 The ma-capability-obj provides information about the capabilities of 898 the measurement agent and consists of the following elements: 900 ma-capability-hardware: A description of the hardware of the device 901 the measurement agent is running on. 903 ma-capability-firmware: A description of the firmware of the device 904 the measurement agent is running on. 906 ma-capability-version: The version of the measurement agent. 908 ma-capability-tags: An optional unordered set of tags that 909 provide additional information about the 910 capabilities of the measurement agent. 912 ma-capability-tasks: An optional unordered set of capability 913 objects for each supported task. 915 3.5.2. Definition of ma-capability-task-obj 917 object { 918 string ma-capability-task-name; 919 ma-registry-obj ma-capability-task-functions<0..*>; 920 string ma-capability-task-version; 921 } ma-capability-task-obj; 923 The ma-capability-task-obj provides information about the capability 924 of a task and consists of the following elements: 926 ma-capability-task-name: A name uniquely identifying a task. 928 ma-capability-task-functions: A possibly empty unordered set of 929 registry entries identifying 930 functions this task implements. 932 ma-capability-task-version: The version of the measurement task. 934 3.5.3. Definition of ma-status-obj 936 object { 937 uuid ma-status-agent-id; 938 uri ma-status-device-id; 939 datetime ma-status-last-started; 940 ma-status-interface-obj ma-status-interfaces<0..*>; 941 [ma-status-schedule-obj ma-status-schedules<0..*>;] 942 [ma-status-suppression-obj ma-status-suppressions<0..*>;] 943 } ma-status-obj; 945 The ma-status-obj provides status information about the measurement 946 agent and consists of the following elements: 948 ma-status-agent-id: A uuid uniquely identifying the measurement 949 agent. 951 ma-status-device-id: A URI identifying the device. 953 ma-status-last-started: The date and time the measurement agent 954 last started. 956 ma-status-interfaces: An unordered set of network interfaces 957 available on the device. 959 ma-status-schedules: An optional unordered set of status objects 960 for each schedule. 962 ma-status-suppressions: An optional unordered set of status objects 963 for each suppression. 965 3.5.4. Definition of ma-status-schedule-obj 967 object { 968 string ma-status-schedule-name; 969 string ma-status-schedule-state; 970 int ma-status-schedule-storage; 971 counter ma-status-schedule-invocations; 972 counter ma-status-schedule-suppressions; 973 counter ma-status-schedule-overlaps; 974 counter ma-status-schedule-failures; 975 datetime ma-status-schedule-last-invocation; 976 [ma-status-action-obj ma-status-schedule-actions<0..*>;] 977 } ma-status-schedule-obj; 979 The ma-status-schedule-obj provides status information about the 980 status of a schedule and consists of the following elements: 982 ma-status-schedule-name: The name of the schedule this 983 status object refers to. 985 ma-status-schedule-state: The state of the schedule. The 986 value 'enabled' indicates that 987 the schedule is currently 988 enabled. The value 'suppressed' 989 indicates that the schedule is 990 currently suppressed. The value 991 'disabled' indicates that the 992 schedule is currently disabled. 993 The value 'running' indicates 994 that the schedule is currently 995 running. 997 ma-status-schedule-storage: The amount of secondary storage 998 (e.g., allocated in a file 999 system) holding temporary data 1000 allocated to the schedule in 1001 bytes. This object reports the 1002 amount of allocated physical 1003 storage and not the storage used 1004 by logical data records. Data 1005 models should use a 64-bit 1006 integer type. 1008 ma-status-schedule-invocations Number of invocations of this 1009 schedule. This counter does not 1010 include suppressed invocations or 1011 invocations that were prevented 1012 due to an overlap with a previous 1013 invocation of this schedule. 1015 ma-status-schedule-suppressions Number of suppressed executions 1016 of this schedule. 1018 ma-status-schedule-overlaps Number of executions prevented 1019 due to overlaps with a previous 1020 invocation of this schedule. 1022 ma-status-schedule-failures Number of failed executions of 1023 this schedule. A failed 1024 execution is an execution where 1025 at least one action failed. 1027 ma-status-schedule-last-invocation: The date and time of the last 1028 invocation of this schedule. 1030 ma-status-schedule-actions: An optional ordered list of 1031 status objects for each action of 1032 the schedule. 1034 3.5.5. Definition of ma-status-action-obj 1035 object { 1036 string ma-status-action-name; 1037 string ma-status-action-state; 1038 int ma-status-action-storage; 1039 counter ma-status-action-invocations; 1040 counter ma-status-action-suppressions; 1041 counter ma-status-action-overlaps; 1042 counter ma-status-action-failures; 1043 datetime ma-status-action-last-invocation; 1044 datetime ma-status-action-last-completion; 1045 int ma-status-action-last-status; 1046 string ma-status-action-last-message; 1047 datetime ma-status-action-last-failed-completion; 1048 int ma-status-action-last-failed-status; 1049 string ma-status-action-last-failed-message; 1050 } ma-status-action-obj; 1052 The ma-status-action-obj provides status information about an action 1053 of a schedule and consists of the following elements: 1055 ma-status-action-name: The name of the action of a 1056 schedule this status object 1057 refers to. 1059 ma-status-action-state: The state of the action. 1060 The value 'enabled' 1061 indicates that the action is 1062 currently enabled. The 1063 value 'suppressed' indicates 1064 that the action is currently 1065 suppressed. The value 1066 'disabled' indicates that 1067 the action is currently 1068 disabled. The value 1069 'running' indicates that the 1070 action is currently running. 1072 ma-status-action-storage: The amount of secondary 1073 storage (e.g., allocated in 1074 a file system) holding 1075 temporary data allocated to 1076 the action in bytes. This 1077 object reports the amount of 1078 allocated physical storage 1079 and not the storage used by 1080 logical data records. Data 1081 models should use a 64-bit 1082 integer type. 1084 ma-status-action-invocations Number of invocations of 1085 this action. This counter 1086 does not include suppressed 1087 invocations or invocations 1088 that were prevented due to 1089 an overlap with a previous 1090 invocation of this action. 1092 ma-status-action-suppressions Number of suppressed 1093 executions of this action. 1095 ma-status-action-overlaps Number of executions 1096 prevented due to overlaps 1097 with a previous invocation 1098 of this action. 1100 ma-status-action-failures Number of failed executions 1101 of this action. 1103 ma-status-action-last-invocation: The date and time of the 1104 last invocation of this 1105 action. 1107 ma-status-action-last-completion: The date and time of the 1108 last completion of this 1109 action. 1111 ma-status-action-last-status: The status code returned by 1112 the last execution of this 1113 action. 1115 ma-status-action-last-message: The status message produced 1116 by the last execution of 1117 this action. 1119 ma-status-action-last-failed-completion: The date and time of the 1120 last failed completion of 1121 this action. 1123 ma-status-action-last-failed-status: The status code returned by 1124 the last failed execution of 1125 this action. 1127 ma-status-action-last-failed-message: The status message produced 1128 by the last failed execution 1129 of this action. 1131 3.5.6. Definition of ma-status-suppression-obj 1133 object { 1134 string ma-status-suppression-name; 1135 string ma-status-suppression-state; 1136 } ma-status-suppression-obj; 1138 The ma-status-suppression-obj provides status information about that 1139 status of a suppression and consists of the following elements: 1141 ma-status-suppression-name: The name of the suppression this status 1142 object refers to. 1144 ma-status-suppression-state: The state of the suppression. The 1145 value 'enabled' indicates that the 1146 suppression is currently enabled. The 1147 value 'active indicates that the 1148 suppression is currently active. The 1149 value 'disabled' indicates that the 1150 suppression is currently disabled. 1152 3.5.7. Definition of ma-status-interface-obj 1154 object { 1155 string ma-status-interface-name; 1156 string ma-status-interface-type; 1157 [int ma-status-interface-speed;] 1158 [string ma-status-interface-link-layer-address;] 1159 [ip-address ma-status-interface-ip-addresses<0..*>;] 1160 [ip-address ma-status-interface-gateways<0..*>;] 1161 [ip-address ma-status-interface-dns-servers<0..*>;] 1162 } ma-status-interface-obj; 1164 The ma-status-interface-obj provides status information about network 1165 interfaces and consists of the following elements: 1167 ma-status-interface-name: A name uniquely identifying a 1168 network interface. 1170 ma-status-interface-type: The type of the network 1171 interface. 1173 ma-status-interface-speed: An optional indication of the 1174 speed of the interface 1175 (measured in bits-per- 1176 second). 1178 ma-status-interface-link-layer-address: An optional link-layer 1179 address of the interface. 1181 ma-status-interface-ip-addresses: An optional ordered list of 1182 IP addresses assigned to the 1183 interface. 1185 ma-status-interface-gateways: An optional ordered list of 1186 gateways assigned to the 1187 interface. 1189 ma-status-interface-dns-servers: An optional ordered list of 1190 DNS servers assigned to the 1191 interface. 1193 3.6. Reporting Information 1195 At a point in time specified by a Schedule, the MA will execute tasks 1196 that communicate a set of measurement results to the Collector. 1197 These Reporting Tasks will be configured to transmit task results 1198 over a specified Report Channel to a Collector. 1200 It should be noted that the output from Tasks does not need to be 1201 sent to communication Channels. It can alternatively, or 1202 additionally, be sent to other Tasks on the MA. This facilitates 1203 using a first Measurement Task to control the operation of a later 1204 Measurement Task (such as first probing available line speed and then 1205 adjusting the operation of a video testing measurement) and also to 1206 allow local processing of data to output alarms (e.g., when 1207 performance drops from earlier levels). Of course, subsequent Tasks 1208 also include Tasks that implement the reporting protocol(s) and 1209 transfer data to one or more Collector(s). 1211 The Report generated by a Reporting Task is structured hierarchically 1212 to avoid repetition of report header and Measurement Task 1213 Configuration information. The report starts with the timestamp of 1214 the report generation on the MA and details about the MA including 1215 the optional Measurement Agent ID and Group ID (controlled by the 1216 Configuration Information). 1218 Much of the report Information is optional and will depend on the 1219 implementation of the Reporting Task and any parameters defined in 1220 the Task Configuration for the Reporting Task. For example some 1221 Reporting Tasks may choose not to include the Measurement Task 1222 Configuration or Action parameters, while others may do so dependent 1223 on the Controller setting a configurable parameter in the Task 1224 Configuration. 1226 It is possible for a Reporting Task to send just the Report header 1227 (datetime and optional agent ID and/or Group ID) if no measurement 1228 data is available. Whether to send such empty reports again is 1229 dependent on the implementation of the Reporting Task and potential 1230 Task Configuration parameter. 1232 The handling of measurement data on the MA before generating a Report 1233 and transfer from the MA to the Collector is dependent on the 1234 implementation of the device, MA and/or scheduled Tasks and not 1235 defined by the LMAP standards. Such decisions may include limits to 1236 the measurement data storage and what to do when such available 1237 storage becomes depleted. It is generally suggested that 1238 implementations running out of storage stop executing new measurement 1239 tasks and retain old measurement data. 1241 No context information, such as line speed or broadband product are 1242 included within the report header information as this data is 1243 reported by individual tasks at the time they execute. Either a 1244 Measurement Task can report contextual parameters that are relevant 1245 to that particular measurement, or specific tasks can be used to 1246 gather a set of contextual and environmental data at certain times 1247 independent of the reporting schedule. 1249 After the report header information the results are reported grouped 1250 according to different Measurement Task Configurations. Each Task 1251 section optionally starts with replicating the Measurement Task 1252 Configuration information before the result headers (titles for data 1253 columns) and the result data rows. The Options reported are those 1254 used for the scheduled execution of the Measurement Task and 1255 therefore include the Options specified in the Task Configuration as 1256 well as additional Options specified in the Action. The Action 1257 Options are appended to the Task Configuration Options in exactly the 1258 same order as they were provided to the Task during execution. 1260 The result row data includes a time for the start of the measurement 1261 and optionally an end time where the duration also needs to be 1262 considered in the data analysis. 1264 Some Measurement Tasks may optionally include an indication of the 1265 cross-traffic although the definition of cross-traffic is left up to 1266 each individual Measurement Task. Some Measurement Tasks may also 1267 output other environmental measures in addition to cross-traffic such 1268 as CPU utlilisation or interface speed. 1270 Where the Configuration and Instruction information represent 1271 information transmitted via the Control Protocol, the Report 1272 represents the information that is transmitted via the Report 1273 Protocol. It is constructed at the time of sending a report and 1274 represents the inherent structure of the information that is sent to 1275 the Collector. 1277 3.6.1. Definition of ma-report-obj 1279 object { 1280 datetime ma-report-date; 1281 [uuid ma-report-agent-id;] 1282 [string ma-report-group-id;] 1283 [string ma-report-measurement-point;] 1284 [ma-report-result-obj ma-report-results<0..*>;] 1285 } ma-report-obj; 1287 The ma-report-obj provides the meta-data of a single report and 1288 consists of the following elements: 1290 ma-report-date: The date and time when the report was 1291 sent to a collector. 1293 ma-report-agent-id: An optional uuid uniquely identifying 1294 the measurement agent. 1296 ma-report-group-id: An optional identifier of the group of 1297 measurement agents this measurement 1298 agent belongs to. 1300 ma-report-measurement-point: An optional identifier for the 1301 measurement point indicating where the 1302 measurement agent is located on a path 1303 (see [RFC7398] for further details). 1305 ma-report-results: An optional and possibly empty 1306 unordered set of result objects. 1308 3.6.2. Definition of ma-report-result-obj 1309 object { 1310 string ma-report-result-schedule-name; 1311 string ma-report-result-action-name; 1312 string ma-report-result-task-name; 1313 [ma-option-obj ma-report-result-options<0..*>;] 1314 [string ma-report-result-tags<0..*>;] 1315 datetime ma-report-result-event-time; 1316 datetime ma-report-result-start-time; 1317 [datetime ma-report-result-end-time;] 1318 [string ma-report-result-cycle-number;] 1319 int ma-report-result-status; 1320 [ma-report-conflict-obj ma-report-result-conflicts<0..*>;] 1321 [ma-report-table-obj ma-report-result-tables<0..*>;] 1322 } ma-report-result-obj; 1324 The ma-report-result-obj provides the meta-data of a result report of 1325 a single executed action. It consists of the following elements: 1327 ma-report-result-schedule-name: The name of the schedule that 1328 produced the result. 1330 ma-report-result-action-name: The name of the action in the 1331 schedule that produced the result. 1333 ma-report-result-task-name: The name of the task that produced 1334 the result. 1336 ma-report-result-options: An optional ordered joined list of 1337 options provided by the task object 1338 and the action object when the action 1339 was started. 1341 ma-report-result-tags: An optional unordered set of tags. 1342 This is the joined set of tags 1343 provided by the task object and the 1344 action object and schedule object 1345 when the action was started. 1347 ma-report-result-event-time: The date and time of the event that 1348 triggered the schedule of the action 1349 that produced the reported result 1350 values. The date and time does not 1351 include any added randomization. 1353 ma-report-result-start-time: The date and time of the start of the 1354 action that produced the reported 1355 result values. 1357 ma-report-result-end-time: An optional date and time indicating 1358 when the action finished. 1360 ma-report-result-cycle-number: An optional cycle number derived from 1361 ma-report-result-event-time. It is 1362 the time closest to ma-report-result- 1363 event-time that is a multiple of the 1364 ma-event-cycle-interval of the event 1365 that triggered the execution of the 1366 schedule. The value is only present 1367 in an ma-report-result-obj if the 1368 event that triggered the execution of 1369 the schedule has a defined ma-event- 1370 cycle-interval. The cycle number is 1371 represented in the format 1372 YYYYMMDD.HHMMSS where YYYY represents 1373 the year, MM the month (1..12), DD 1374 the day of the months (01..31), HH 1375 the hour (00..23), MM the minute 1376 (00..59), and SS the second (00..59). 1377 The cycle number is using Coordinated 1378 Universal Time (UTC). 1380 ma-report-result-status: The status code returned by the 1381 execution of the action. 1383 ma-report-result-conflicts: A possibly empty set of conflict 1384 actions that might have impacted the 1385 measurement results being reported. 1387 ma-report-result-tables: An optional and possibly empty 1388 unordered set of result tables. 1390 3.6.3. Definition of ma-report-conflict-obj 1392 object { 1393 string ma-report-conflict-schedule-name; 1394 string ma-report-conflict-action-name; 1395 string ma-report-conflict-task-name; 1396 } ma-report-conflict-obj; 1398 The ma-report-conflict-obj provides the information about conflicting 1399 action that might have impacted the measurement results. It consists 1400 of the following elements: 1402 ma-report-result-schedule-name: The name of the schedule that may 1403 have impacted the result. 1405 ma-report-result-action-name: The name of the action in the 1406 schedule that may have impacted the 1407 result. 1409 ma-report-result-task-name: The name of the task that may have 1410 impacted the result. 1412 3.6.4. Definition of ma-report-table-obj 1414 object { 1415 [ma-registry-obj ma-report-table-functions<0..*>;] 1416 [string] ma-report-table-column-labels<0..*>;] 1417 [ma-report-row-obj ma-report-table-rows<0..*>;] 1418 } ma-report-table-obj; 1420 The ma-report-table-obj represents a result table and consists of the 1421 following elements: 1423 ma-report-table-functions: An optional and possibly empty 1424 unordered set of registry entries 1425 identifying the functions for which 1426 results that are reported. 1428 ma-report-table-column-labels: An optional and possibly empty 1429 ordered list of column labels. 1431 ma-report-table-rows: A possibly empty ordered list of 1432 result rows. 1434 3.6.5. Definition of ma-report-row-obj 1436 object { 1437 data ma-report-row-values<0..*>; 1438 } ma-report-row-obj; 1440 The ma-report-row-obj represents a result row and consists of the 1441 following elements: 1443 ma-report-row-values: A possibly empty ordered list of result 1444 values. When present, it contains an 1445 ordered list of values that align to the 1446 set of column labels for the report. 1448 3.7. Common Objects: Schedules 1450 A Schedule specifies the execution of a single or repeated series of 1451 Actions. An Action is a Task with additional specific parameters. 1452 Each Schedule contains basically two elements: an ordered list of 1453 Actions to be executed and an Event object triggering the execution 1454 of the Schedule. The Schedule states what Actions to run (with what 1455 configuration) and when to run the Actions. A Schedule may 1456 optionally have an Event that stops the execution of the Schedule or 1457 a maximum duration after which a schedule is stopped. 1459 Multiple Actions contained as an ordered list of a single Measurement 1460 Schedule will be executed according to the execution mode of the 1461 Schedule. In sequential mode, Actions will be executed sequentially 1462 and in parallel mode, all Actions will be executed concurrently. In 1463 pipelined mode, data produced by one Action is passed to the 1464 subsequent Action. Actions contained in different Schedules execute 1465 in parallel with such conflicts being reported in the Reporting 1466 Information where necessary. If two or more Schedules have the same 1467 start time, then the two will execute in parallel. There is no 1468 mechanism to prioritise one schedule over another or to mutex 1469 scheduled tasks. 1471 As well as specifying which Actions to execute, the Schedule also 1472 specifies how to link the data outputs from each Action to other 1473 Schedules. Specifying this within the Schedule allows the highest 1474 level of flexibility since it is even possible to send the output 1475 from different executions of the same Task Configuration to different 1476 destinations. A single Task producing multiple different outputs is 1477 expected to properly tag the different result. An Action receiving 1478 the output can then filter the results based on the tag if necessary. 1479 For example, a Measurement Task might report routine results to a 1480 data Reporting Task in a Schedule that communicates hourly via the 1481 Broadband PPP interface, but also outputs emergency conditions via an 1482 alarm Reporting Task in a different Schedule communicating 1483 immediately over a GPRS channel. Note that task-to-task data 1484 transfer is always specified in association with the scheduled 1485 execution of the sending task - there is no need for a corresponding 1486 input specification for the receiving task. While it is likely that 1487 an MA implementation will use a queue mechanism between the Schedules 1488 or Actions, this Information Model does not mandate or define a 1489 queue. The Information Model, however, reports the storage allocated 1490 to Schedules and Actions so that storage usage can be monitored. 1491 Furthermore, it is recommended that MA implementations by default 1492 retain old data and stop the execution of new measurement tasks if 1493 the MA runs out of storage capacity. 1495 When specifying the task to execute within the Schedule, i.e., 1496 creating an Action, it is possible to add to the Action option 1497 parameters. This allows the Task Configuration to determine the 1498 common characteristics of a Task, while selected parameters (e.g., 1499 the test target URL) are defined within as option parameters of the 1500 Action in the schedule. A single Tasks Configuration can even be 1501 used multiple times in the same schedule with different additional 1502 parameters. This allows for efficiency in creating and transferring 1503 the Instruction. Note that the semantics of what happens if an 1504 option is defined multiple times (either in the Task Configuration, 1505 Action or in both) is not standardised and will depend upon the Task. 1506 For example, some tasks may legitimately take multiple values for a 1507 single parameter. 1509 Where Options are specified in both the Action and the Task 1510 Configuration, the Action Options are appended to those specified in 1511 the Task Configuration. 1513 Example: An Action of a Schedule references a single Measurement 1514 Task Configuration for measuring UDP latency. It specifies that 1515 results are to be sent to a Schedule with a Reporting Action. 1516 This Reporting Task of the Reporting Action is executed by a 1517 separate Schedule that specifies that it should run hourly at 5 1518 minutes past the hour. When run this Reporting Action takes the 1519 data generated by the UDP latency Measurement Task as well as any 1520 other data to be included in the hourly report and transfers it to 1521 the Collector over the Report Channel specified within its own 1522 Schedule. 1524 Schedules and Actions may optionally also be given tags that are 1525 included in result reports sent to a Collector. In addition, 1526 schedules can be given suppression tags that may be used to select 1527 Schedules and Actions for suppression. 1529 3.7.1. Definition of ma-schedule-obj 1531 object { 1532 string ma-schedule-name; 1533 ma-event-obj ma-schedule-start; 1534 [ma-event-obj ma-schedule-end;] 1535 [int ma-schedule-duration;] 1536 ma-action-obj ma-schedule-actions<0..*>; 1537 string ma-schedule-execution-mode; 1538 [string ma-schedule-tags<0..*>;] 1539 [string ma-schedule-suppression-tags<0..*>;] 1540 } ma-schedule-obj; 1542 The ma-schedule-obj is the main scheduling object. It consists of 1543 the following elements: 1545 ma-schedule-name: A name uniquely identifying a 1546 scheduling object. 1548 ma-schedule-start: An event object indicating when the 1549 schedule starts. 1551 ma-schedule-end: An optional event object controlling 1552 the forceful termination of scheduled 1553 actions. When the event occurs, all 1554 actions of the schedule will be forced 1555 to terminate gracefully. 1557 ma-schedule-duration: An optional duration in seconds for the 1558 schedule. All actions of the schedule 1559 will be forced to terminate gracefully 1560 after the duration number of seconds 1561 past the start of the schedule. 1563 ma-schedule-actions: A possibly empty ordered list of 1564 actions to invoke when the schedule 1565 starts. 1567 ma-schedule-execution-mode: Indicates whether the actions should be 1568 executed sequentially, in parallel, or 1569 in a pipelined mode (where data 1570 produced by one action is passed to the 1571 subsequent action). The default 1572 execution mode is pipelined. 1574 ma-schedule-tags: An optional unordered set of tags that 1575 are reported together with the 1576 measurement results to a collector. 1578 ma-schedule-suppression-tags: An optional unordered set of 1579 suppression tags that are used to 1580 select schedules to be suppressed. 1582 3.7.2. Definition of ma-action-obj 1584 object { 1585 string ma-action-name; 1586 string ma-action-config-task-name; 1587 [ma-option-obj ma-action-task-options<0..*>;] 1588 [string ma-action-destinations<0..*>;] 1589 [string ma-action-tags<0..*>;] 1590 [string ma-action-suppression-tags<0..*>;] 1591 } ma-action-obj; 1593 The ma-action-obj models a task together with its schedule specific 1594 task options and destination schedules. It consists of the following 1595 elements: 1597 ma-action-name: A name uniquely identifying an action 1598 of a scheduling object. 1600 ma-action-config-task-name: A name identifying the configured task 1601 to be invoked by the action. 1603 ma-action-task-options: An optional and possibly empty ordered 1604 list of options (name-value pairs) that 1605 are passed to the task by appending 1606 them to the options configured for the 1607 task object. 1609 ma-action-destinations: An optional and possibly empty 1610 unordered set of names of destination 1611 schedules that consume output produced 1612 by this action. 1614 ma-action-tags: An optional unordered set of tags that 1615 are reported together with the 1616 measurement results to a collector. 1618 ma-action-suppression-tags: An optional unordered set of 1619 suppression tags that are used to 1620 select actions to be suppressed. 1622 3.8. Common Objects: Channels 1624 A Channel defines a bi-directional communication channel between the 1625 MA and a Controller or Collector. Multiple Channels can be defined 1626 to enable results to be split or duplicated across different 1627 Collectors. 1629 Each Channel contains the details of the remote endpoint (including 1630 location and security credential information such as the 1631 certificate). The timing of when to communicate over a Channel is 1632 specified by the Schedule which executes the corresponding Control or 1633 Reporting Task. The certificate can be the digital certificate 1634 associated to the FQDN in the URL or it can be the certificate of the 1635 Certification Authority that was used to issue the certificate for 1636 the FQDN (Fully Qualified Domain Name) of the target URL (which will 1637 be retrieved later on using a communication protocol such as TLS). 1638 In order to establish a secure channel, the MA will use it's own 1639 security credentials (in the Configuration Information) and the given 1640 credentials for the individual Channel end-point. 1642 As with the Task Configurations, each Channel is also given a text 1643 name by which it can be referenced as a Task Option. 1645 Although the same in terms of information, Channels used for 1646 communication with the Controller are referred to as Control Channels 1647 whereas Channels to Collectors are referred to as Report Channels. 1648 Hence Control Channels will be referenced from Control Tasks executed 1649 by a Control Schedule, whereas Report Channels will be referenced 1650 from within Reporting Tasks executed by an Instruction Schedule. 1652 Multiple interfaces are also supported. For example the Reporting 1653 Task could be configured to send some results over GPRS. This is 1654 especially useful when such results indicate the loss of connectivity 1655 on a different network interface. 1657 Example: A Channel used for reporting results may specify that 1658 results are to be sent to the URL (https://collector.example.org/ 1659 report/), using the appropriate digital certificate to establish a 1660 secure channel. 1662 3.8.1. Definition of ma-channel-obj 1664 object { 1665 string ma-channel-name; 1666 url ma-channel-target; 1667 credentials ma-channel-credentials; 1668 [string ma-channel-interface-name;] 1669 } ma-channel-obj; 1671 The ma-channel-obj consists of the following elements: 1673 ma-channel-name: A unique name identifying the channel 1674 object. 1676 ma-channel-target: A URL identifying the target channel 1677 endpoint. 1679 ma-channel-credentials: The security credentials needed to 1680 establish a secure channel. 1682 ma-channel-interface-name: An optional name of the network interface 1683 to be used. If not present, the IP 1684 protocol stack will select a suitable 1685 interface. 1687 3.9. Common Objects: Task Configurations 1689 Conceptually each Task Configuration defines the parameters of a Task 1690 that the Measurement Agent (MA) may perform at some point in time. 1691 It does not by itself actually instruct the MA to perform them at any 1692 particular time (this is done by a Schedule). Tasks can be 1693 Measurement Tasks (i.e., those Tasks actually performing some type of 1694 passive or active measurement) or any other scheduled activity 1695 performed by the MA such as transferring information to or from the 1696 Controller and Collectors. Other examples of Tasks may include data 1697 manipulation or processing Tasks conducted on the MA. 1699 A Measurement Task Configuration is the same in information terms to 1700 any other Task Configuration. Both measurement and non-measurement 1701 Tasks have registry entries to enable the MA to uniquely identify the 1702 Task it should execute and retrieve the schema for any parameters 1703 that may be passed to the Task. Registry entries are specified as a 1704 URI and can therefore be used to identify the Task within a namespace 1705 or point to a web or local file location for the Task information. 1706 As mentioned previously, these URIs may be used to identify the 1707 Measurement Task in a public namespace 1708 [I-D.ietf-ippm-metric-registry]. 1710 Example: A Measurement Task Configuration may configure a single 1711 Measurement Task for measuring UDP latency. The Measurement Task 1712 Configuration could define the destination port and address for 1713 the measurement as well as the duration, internal packet timing 1714 strategy and other parameters (for example a stream for one hour 1715 and sending one packet every 500 ms). It may also define the 1716 output type and possible parameters (for example the output type 1717 can be the 95th percentile mean) where the measurement task 1718 accepts such parameters. It does not define when the task starts 1719 (this is defined by the Schedule element), so it does not by 1720 itself instruct the MA to actually perform this Measurement Task. 1722 The Task Configuration will include a local short name for reference 1723 by a Schedule. Task Configurations may also refer to registry 1724 entries as described above. In addition the Task can be configured 1725 through a set of configuration Options. The nature and number of 1726 these Options will depend upon the Task. These options are expressed 1727 as name-value pairs although the 'value' may be a structured object 1728 instead of a simple string or numeric value. The implementation of 1729 these name-value pairs will vary between data models. 1731 An Option that must be present for Reporting Tasks is the Channel 1732 reference specifying how to communicate with a Collector. This is 1733 included in the task options and will have a value that matches a 1734 channel name that has been defined in the Instruction. Similarly 1735 Control Tasks will have a similar option with the value set to a 1736 specified Control Channel. 1738 A Reporting Task might also have a flag parameter, defined as an 1739 Option, to indicate whether to send a report without measurement 1740 results if there is no measurement result data pending to be 1741 transferred to the Collector. In addition many tasks will also take 1742 as a parameter which interface to operate over. 1744 In addition the Task Configuration may optionally also be given tags 1745 that can carry a Measurement Cycle ID. The purpose of this ID is to 1746 easily identify a set of measurement results that have been produced 1747 by Measurement Tasks with comparable Options. This ID could be 1748 manually incremented or otherwise changed when an Option change is 1749 implemented which could mean that two sets of results should not be 1750 directly compared. 1752 3.9.1. Definition of ma-task-obj 1754 object { 1755 string ma-task-name; 1756 ma-registry-obj ma-task-functions<0..*>; 1757 [ma-option-obj ma-task-options<0..*>;] 1758 [string ma-task-tags<0..*>;] 1759 } ma-task-obj; 1761 The ma-task-obj defines a configured task that can be invoked as part 1762 of an action. A configured task can be referenced by its name and it 1763 contains a set of URIs to link to registry entries or a local 1764 specification of the task. Options allow the configuration of task 1765 parameters (in the form of name-value pairs). The ma-task-obj 1766 consists of the following elements: 1768 ma-task-name: A name uniquely identifying a configured 1769 task object. 1771 ma-task-functions: A possibly empty unordered set of registry 1772 entries identifying the functions of the 1773 configured task. 1775 ma-task-options: An optional and possibly empty ordered list 1776 of options (name-value pairs) that are 1777 passed to the configured task. 1779 ma-task-tags: An optional unordered set of tags that are 1780 reported together with the measurement 1781 results to a collector. 1783 3.9.2. Definition of ma-option-obj 1785 object { 1786 string ma-option-name; 1787 [object ma-option-value;] 1788 } ma-option-obj; 1790 The ma-option-obj models a name-value pair and consists of the 1791 following elements: 1793 ma-option-name: The name of the option. 1795 ma-option-value: The optional value of the option. 1797 The ma-option-obj is used to define Task Configuration Options. Task 1798 Configuration Options are generally task specific. For tasks 1799 associated with an entry in a registry, the registry may define well- 1800 known option names (e.g., the so-called parameters in the IPPM metric 1801 registry [I-D.ietf-ippm-metric-registry]). Control and Reporting 1802 Tasks need to know the Channel they are going to use. The common 1803 option name for specifying the channel is "channel" where the 1804 option's value refers to the name of an ma-channel-obj. 1806 3.10. Common Objects: Registry Information 1808 Tasks and actions can be associated with entries in a registry. A 1809 registry object refers to an entry in a registry (identified by a 1810 URI) and it may define a set of roles. 1812 3.10.1. Definition of ma-registry-obj 1814 object { 1815 uri ma-registry-uri; 1816 [string ma-registry-role<0..*>;] 1817 } ma-registry-obj; 1819 The ma-registry-obj refers to an entry of a registry and it defines 1820 the associated role(s). The ma-registry-obj consists of the 1821 following elements: 1823 ma-registry-uri: A URI identifying an entry in a registry. 1825 ma-registry-role: An optional and possibly empty unordered 1826 set of roles for the identified registry 1827 entry. 1829 3.11. Common Objects: Event Information 1831 The Event information object used throughout the information models 1832 can initially take one of several different forms. Additional forms 1833 may be defined later in order to bind the execution of schedules to 1834 additional events. The initially defined Event forms are: 1836 1. Periodic Timing: Emits multiple events periodically according to 1837 an interval time defined in seconds 1839 2. Calendar Timing: Emits multiple events according to a calendar 1840 based pattern, e.g., 22 minutes past each hour of the day on 1841 weekdays 1843 3. One Off Timing: Emits one event at a specific date and time 1845 4. Immediate: Emits one event as soon as possible 1847 5. Startup: Emits an event whenever the MA is started (e.g., at 1848 device startup) 1850 6. Controller Lost: Emits an event when connectivity to the 1851 controller has been lost 1853 7. Controller Connected: Emits an event when connectivity to the 1854 controller has been (re-)established 1856 Optionally each of the Event options may also specify a randomness 1857 that should be evaluated and applied separately to each indicated 1858 event. This randomness parameter defines a uniform interval in 1859 seconds over which the start of the task is delayed from the starting 1860 times specified by the event object. 1862 Both the Periodic and Calendar timing objects allow for a series of 1863 Actions to be executed. While both have an optional end time, it is 1864 best practice to always configure an end time and refresh the 1865 information periodically to ensure that lost MAs do not continue 1866 their tasks forever. 1868 Startup events are only created on device startup, not when a new 1869 Instruction is transferred to the MA. If scheduled task execution is 1870 desired both on the transfer of the Instruction and on device restart 1871 then both the Immediate and Startup timing needs to be used in 1872 conjunction. 1874 The datetime format used for all elements in the information model 1875 MUST conform to RFC 3339 [RFC3339]. 1877 3.11.1. Definition of ma-event-obj 1878 object { 1879 string ma-event-name; 1880 union { 1881 ma-periodic-obj ma-event-periodic; 1882 ma-calendar-obj ma-event-calendar; 1883 ma-one-off-obj ma-event-one-off; 1884 ma-immediate-obj ma-event-immediate; 1885 ma-startup-obj ma-event-startup; 1886 ma-controller-lost-obj ma-event-controller-lost; 1887 ma-controller-connected-obj ma-event-controller-connected; 1888 } 1889 [int ma-event-random-spread;] 1890 [int ma-event-cycle-interval;] 1891 } ma-event-obj; 1893 The ma-event-obj is the main event object. Event objects are 1894 identified by a name. A generic event object itself contains a more 1895 specific event object. The set of specific event objects should be 1896 extensible. The initial set of specific event objects is further 1897 described below. The ma-event-obj also includes an optional uniform 1898 random spread that can be used to randomize the start times of 1899 schedules triggered by an event. The ma-event-obj consists of the 1900 following elements: 1902 ma-event-name: The name uniquely identifies an event 1903 object. Schedules refer to event 1904 objects by this name. 1906 ma-event-periodic: The ma-event-periodic is present for 1907 periodic timing objects. 1909 ma-event-calendar: The ma-event-calendar is present for 1910 calendar timing objects. 1912 ma-event-one-off: The ma-event-one-off is present for 1913 one-off timing objects. 1915 ma-event-immediate: The ma-event-immediate is present for 1916 immediate event objects. 1918 ma-event-startup: The ma-event-startup is present for 1919 startup event objects. 1921 ma-event-controller-lost: The ma-event-controller-lost is 1922 present for connectivity to 1923 controller lost event objects. 1925 ma-event-controller-connected: The ma-event-controller-connected is 1926 present for connectivity to a 1927 controller established event objects. 1929 ma-event-random-spread: The optional ma-event-random-spread 1930 adds a random delay defined in 1931 seconds to the event object. No 1932 random delay is added if ma-event- 1933 random-spread does not exist. 1935 ma-event-cycle-interval: The optional ma-event-cycle-interval 1936 defines the duration of the time 1937 interval in seconds that is used to 1938 calculate cycle numbers. No cycle 1939 number is calculated if ma-event- 1940 cycle-interval does not exist. 1942 3.11.2. Definition of ma-periodic-obj 1944 object { 1945 [datetime ma-periodic-start;] 1946 [datetime ma-periodic-end;] 1947 int ma-periodic-interval; 1948 } ma-periodic-obj; 1950 The ma-periodic-obj timing object has an optional start and an 1951 optional end time plus a periodic interval. Schedules using an ma- 1952 periodic-obj are started periodically between the start and end time. 1953 The ma-periodic-obj consists of the following elements: 1955 ma-periodic-start: The optional date and time at which 1956 Schedules using this object are first 1957 started. If not present it defaults to 1958 immediate. 1960 ma-periodic-end: The optional date and time at which 1961 Schedules using this object are last 1962 started. If not present it defaults to 1963 indefinite. 1965 ma-periodic-interval: The interval defines the time in seconds 1966 between two consecutive starts of tasks. 1968 3.11.3. Definition of ma-calendar-obj 1970 Calendar Timing supports the routine execution of Schedules at 1971 specific times and/or on specific dates. It can support more 1972 flexible timing than Periodic Timing since the execution of Schedules 1973 does not have to be uniformly spaced. For example a Calendar Timing 1974 could support the execution of a Measurement Task every hour between 1975 6pm and midnight on weekdays only. 1977 Calendar Timing is also required to perform measurements at 1978 meaningful times in relation to network usage (e.g., at peak times). 1979 If the optional timezone offset is not supplied then local system 1980 time is assumed. This is essential in some use cases to ensure 1981 consistent peak-time measurements as well as supporting MA devices 1982 that may be in an unknown timezone or roam between different 1983 timezones (but know their own timezone information such as through 1984 the mobile network). 1986 The calendar elements within the Calendar Timing do not have defaults 1987 in order to avoid accidental high-frequency execution of Tasks. If 1988 all possible values for an element are desired then the wildcard * is 1989 used. 1991 object { 1992 [datetime ma-calendar-start;] 1993 [datetime ma-calendar-end;] 1994 [string ma-calendar-months<0..*>;] 1995 [string ma-calendar-days-of-week<0..*>;] 1996 [string ma-calendar-days-of-month<0..*>;] 1997 [string ma-calendar-hours<0..*>;] 1998 [string ma-calendar-minutes<0..*>;] 1999 [string ma-calendar-seconds<0..*>;] 2000 [int ma-calendar-timezone-offset;] 2001 } ma-calendar-obj; 2003 ma-calendar-start: The optional date and time at which 2004 Schedules using this object are first 2005 started. If not present it defaults to 2006 immediate. 2008 ma-calendar-end: The optional date and time at which 2009 Schedules using this object are last 2010 started. If not present it defaults to 2011 indefinite. 2013 ma-calendar-months: The optional set of months (1-12) on 2014 which tasks scheduled using this object 2015 are started. The wildcard * means all 2016 months. If not present, it defaults to 2017 no months. 2019 ma-calendar-days-of-week: The optional set of days of a week 2020 ("Mon", "Tue", "Wed", "Thu", "Fri", 2021 "Sat", "Sun") on which tasks scheduled 2022 using this object are started. The 2023 wildcard * means all days of the week. 2024 If not present, it defaults to no days. 2026 ma-calendar-days-of-month: The optional set of days of a months 2027 (1-31) on which tasks scheduled using 2028 this object are started. The wildcard 2029 * means all days of a months. If not 2030 present, it defaults to no days. 2032 ma-calendar-hours: The optional set of hours (0-23) on 2033 which tasks scheduled using this object 2034 are started. The wildcard * means all 2035 hours of a day. If not present, it 2036 defaults to no hours. 2038 ma-calendar-minutes: The optional set of minutes (0-59) on 2039 which tasks scheduled using this object 2040 are started. The wildcard * means all 2041 minutes of an hour. If not present, it 2042 defaults to no hours. 2044 ma-calendar-seconds: The optional set of seconds (0-59) on 2045 which tasks scheduled using this object 2046 are started. The wildcard * means all 2047 seconds of an hour. If not present, it 2048 defaults to no seconds. 2050 ma-calendar-timezone-offset: The optional timezone offest in hours. 2051 If not present, it defaults to the 2052 system's local timezone. 2054 If a day of the month is specified that does not exist in the month 2055 (e.g., 29th of Feburary) then those values are ignored. 2057 3.11.4. Definition of ma-one-off-obj 2059 object { 2060 datetime ma-one-off-time; 2061 } ma-one-off-obj; 2063 The ma-one-off-obj timing object specifies a fixed point in time. 2064 Schedules using an ma-one-off-obj are started once at the specified 2065 date and time. The ma-one-off-obj consists of the following 2066 elements: 2068 ma-one-off-time: The date and time at which Schedules using 2069 this object are started. 2071 3.11.5. Definition of ma-immediate-obj 2073 object { 2074 // empty 2075 } ma-immediate-obj; 2077 The ma-immediate-obj event object has no further information 2078 elements. Schedules using an ma-immediate-obj are started as soon as 2079 possible. 2081 3.11.6. Definition of ma-startup-obj 2083 object { 2084 // empty 2085 } ma-startup-obj; 2087 The ma-startup-obj event object has no further information elements. 2088 Schedules or suppressions using an ma-startup-obj are started at MA 2089 initialization time. 2091 3.11.7. Definition of ma-controller-lost-obj 2093 object { 2094 // empty 2095 } ma-controller-lost-obj; 2097 The ma-controller-lost-obj event object has no further information 2098 elements. The ma-controller-lost-obj indicates that connectivity to 2099 the controller has been lost. This is determined by a timer started 2100 after each successful contact with a controller. When the timer 2101 reaches the controller-timeout (measured in seconds), an ma- 2102 controller-lost-obj event is generated. This event may be used to 2103 start a suppression. 2105 3.11.8. Definition of ma-controller-connected-obj 2107 object { 2108 // empty 2109 } ma-controller-connected-obj; 2111 The ma-controller-connected-obj event object has no further 2112 information elements. The ma-controller-connected-obj indicates that 2113 connectivity to the controller has been established again after it 2114 was lost. This event may be used to end a suppression. 2116 4. Example Execution 2118 The example execution has two event sources E1 and E2 and three 2119 schedules S1, S2, and S3. The schedule S3 is started by events of 2120 event source E2 while the schedules S1 and S2 are both started by 2121 events of the event source E1. The schedules S1 and S2 have two 2122 actions each and schedule S3 has a single action. The event source 2123 E2 has no randomization while the event source E1 has the 2124 randomization r. 2126 Figure 2 shows a possible timeline of an execution. The time T is 2127 progressing downwards. The dotted vertial line indicates progress of 2128 time while a dotted horizontal line indicates which schedule are 2129 triggered by an event. Tilded lines indicate data flowing from an 2130 action to another schedule. Actions within a schedule are named A1, 2131 A2, etc. 2133 E2 E1 T S1 S2 S3 2134 sequential parallel pipelined 2135 : 2136 e0 + 2137 : 2138 : 2139 e0+r + .......... + .......... ++ 2140 : | A1 A1 || A2 2141 : + |+ ~~~~~~~> 2142 : | A2 | 2143 : | + ~~~~~~~~> 2144 : + ~~~~~~~~~~~~~~~~~~~~~> 2145 : 2146 : 2147 e1 + 2148 : 2149 e1+r + .......... + .......... ++ 2150 : | A1 A1 || 2151 : | +|~~~~~~~> 2152 : | | A2 2153 : + +~~~~~~~> 2154 : | A2 2155 : + ~~~~~~~~~~~~~~~~~~~~> 2156 e0 + ................................... + 2157 : | A1 2158 e3 + | 2159 e3+r + .......... + .......... ++ | 2160 : | A1 A1 || A2 | 2161 : + ++ ~~~~~~> | 2162 : | A2 + 2163 : + ~~~~~~~~~~~~~~~~~~~~> 2164 V 2166 Figure 2: Example Execution 2168 Note that implementations must handle possible concurrency issues. 2169 In the example execution, action A1 of schedule S3 is consuming the 2170 data that has been forwarded to schedule S3 while additional data is 2171 arriving from action A2 of schedule S2. 2173 5. IANA Considerations 2175 This document makes no request of IANA. 2177 Note to the RFC Editor: this section may be removed on publication as 2178 an RFC. 2180 6. Security Considerations 2182 This Information Model deals with information about the control and 2183 reporting of the Measurement Agent. There are broadly two security 2184 considerations for such an Information Model. Firstly the 2185 Information Model has to be sufficient to establish secure 2186 communication channels to the Controller and Collector such that 2187 other information can be sent and received securely. Additionally, 2188 any mechanisms that the Network Operator or other device 2189 administrator employs to pre-configure the MA must also be secure to 2190 protect unauthorized parties from modifying pre-configuration 2191 information. These mechanisms are important to ensure that the MA 2192 cannot be hijacked, for example to participate in a distributed 2193 denial of service attack. 2195 The second consideration is that no mandated information items should 2196 pose a risk to confidentiality or privacy given such secure 2197 communication channels. For this latter reason items such as the MA 2198 context and MA ID are left optional and can be excluded from some 2199 deployments. This would, for example, allow the MA to remain 2200 anonymous and for information about location or other context that 2201 might be used to identify or track the MA to be omitted or blurred. 2203 The Information Model should support wherever relevant, all the 2204 security and privacy requirements associated with the LMAP Framework. 2206 7. Acknowledgements 2208 Several people contributed to this specification by reviewing early 2209 versions and actively participating in the LMAP working group 2210 (apologies to those unintentionally omitted): Vaibhav Bajpai, Michael 2211 Bugenhagen, Timothy Carey, Alissa Cooper, Kenneth Ko, Al Morton, Dan 2212 Romascanu, Henning Schulzrinne, Andrea Soppera, Barbara Stark, and 2213 Jason Weil. 2215 Trevor Burbridge, Philip Eardley, Marcelo Bagnulo and Juergen 2216 Schoenwaelder worked in part on the Leone research project, which 2217 received funding from the European Union Seventh Framework Programme 2218 [FP7/2007-2013] under grant agreement number 317647. 2220 Juergen Schoenwaelder was partly funded by Flamingo, a Network of 2221 Excellence project (ICT-318488) supported by the European Commission 2222 under its Seventh Framework Programme. 2224 8. References 2226 8.1. Normative References 2228 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2229 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 2230 RFC2119, March 1997, 2231 . 2233 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 2234 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 2235 . 2237 8.2. Informative References 2239 [I-D.ietf-ippm-metric-registry] 2240 Bagnulo, M., Claise, B., Eardley, P., Morton, A., and A. 2241 Akhter, "Registry for Performance Metrics", draft-ietf- 2242 ippm-metric-registry-10 (work in progress), November 2016. 2244 [I-D.ietf-lmap-yang] 2245 Schoenwaelder, J. and V. Bajpai, "A YANG Data Model for 2246 LMAP Measurement Agents", draft-ietf-lmap-yang-08 (work in 2247 progress), November 2016. 2249 [RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between 2250 Information Models and Data Models", RFC 3444, DOI 10 2251 .17487/RFC3444, January 2003, 2252 . 2254 [RFC7398] Bagnulo, M., Burbridge, T., Crawford, S., Eardley, P., and 2255 A. Morton, "A Reference Path and Measurement Points for 2256 Large-Scale Measurement of Broadband Performance", RFC 2257 7398, DOI 10.17487/RFC7398, February 2015, 2258 . 2260 [RFC7594] Eardley, P., Morton, A., Bagnulo, M., Burbridge, T., 2261 Aitken, P., and A. Akhter, "A Framework for Large-Scale 2262 Measurement of Broadband Performance (LMAP)", RFC 7594, 2263 DOI 10.17487/RFC7594, September 2015, 2264 . 2266 Appendix A. Change History 2268 Note to the RFC Editor: this section should be removed on publication 2269 as an RFC. 2271 A.1. Non-editorial changes since -15 2273 o The reference to the framework is now informational. 2275 A.2. Non-editorial changes since -14 2277 o Clarified that the cycle number is in UTC. 2279 A.3. Non-editorial changes since -13 2281 o Removed the ma-config-device-id from the ma-config-obj. 2283 o Added ma-config-report-group-id and clarified how two flags ma- 2284 config-report-agent-id and ma-config-report-group-id work. 2286 A.4. Non-editorial changes since -12 2288 o Renamed the ma-metrics-registry-obj to ma-registry-obj since tasks 2289 may refer to different registries (not just a metrics registry). 2291 o Clarifications and bug fixes. 2293 A.5. Non-editorial changes since -11 2295 o Clarifications and bug fixes. 2297 A.6. Non-editorial changes since -10 2299 o Rewrote the text concerning the well-known "channel" option name. 2301 o Added ma-report-result-event-time, ma-report-result-cycle-number, 2302 and ma-event-cycle-interval. 2304 o Added ma-capability-tags. 2306 o Added a new section showing an example execution. 2308 o Several clarifications and bug fixes. 2310 A.7. Non-editorial changes since -09 2312 o Added ma-status-schedule-storage and ma-status-action-storage. 2314 o Removed suppress-by-default. 2316 o Moved ma-report-result-metrics of the ma-report-result-obj to ma- 2317 report-table-metrics of the ma-report-table-obj so that the 2318 relationship between metrics and result tables is clear. 2320 o Added ma-report-conflict-obj. 2322 o Added ma-report-result-status to ma-report-result-obj. 2324 o Several clarifications and bug fixes. 2326 A.8. Non-editorial changes since -08 2328 o Refactored the ma-report-task-obj into the ma-report-result-obj. 2330 o Introduced the ma-report-table-obj so that a result can contain 2331 multiple tables. 2333 o Report schedule, action, and task name as part of the ma-report- 2334 result-obj. 2336 o Report conflicts per ma-report-result-obj and not per ma-report- 2337 row-obj. 2339 o Report the start/end time as part of the ma-report-result-obj. 2341 A.9. Non-editorial changes since -07 2343 o Added ma-schedule-end and ma-schedule-duration. 2345 o Changed the granularity of scheduler timings to seconds. 2347 o Added ma-status-suppression-obj to report the status of 2348 suppressions as done in the YANG data model. 2350 o Added counters to schedule and action status objects to match the 2351 counters in the YANG data model. 2353 o Using tags to pass information such as a measurement cycle 2354 identifier to the collector. 2356 o Using suppression tags and glob-style matching to select schedules 2357 and actions to be suppressed. 2359 A.10. Non-editorial changes since -06 2361 o The default execution mode is pipelined (LI12) 2363 o Added text to define which action consumes data in sequential, 2364 pipelines, and parallel execution mode (LI11) 2366 o Added ma-config-measurement-point, ma-report-measurement-point, 2367 and ma-config-report-measurement-point to configure and report the 2368 measurement point (LI10) 2370 o Turned ma-suppression-obj into a list that uses a start event and 2371 a stop event to define the start and end of suppression; this 2372 unifies the handling of suppression and loss of controller 2373 connectivity (LI09) 2375 o Added ma-controller-lost-obj and ma-controller-ok-obj event 2376 objects (LI09) 2378 o Added ma-status-schedule-obj to report the status of a schedule 2379 and refactored ma-task-status-obj into ma-status-action-obj to 2380 report the status of an action (LI07, LI08) 2382 o Introduced a common ma-metric-registry-obj that identifies a 2383 metric and a set of associated roles and added this object to 2384 expose metric capabilities and to support the configuration of 2385 metrics and to report the metrics used (LI06) 2387 o Introduced ma-capability-obj and ma-capability-task-obj to expose 2388 the capabilities of a measurement agent (LI05) 2390 o Use 'ordered list' or 'unordered set' instead of list, collection, 2391 etc. (LI02) 2393 o Clarification that Actions are part of a Schedule (LI03) 2395 o Deleted terms that are not strictly needed (LI04) 2397 A.11. Non-editorial changes since -05 2399 o A task can now reference multiply registry entries. 2401 o Consistent usage of the term Action and Task. 2403 o Schedules are triggered by Events instead of Timings; Timings are 2404 just one of many possible event sources. 2406 o Actions feed into other Schedules (instead of Actions within other 2407 Schedules). 2409 o Removed the notion of multiple task outputs. 2411 o Support for sequential, parallel, and pipelined execution of 2412 Actions. 2414 Authors' Addresses 2416 Trevor Burbridge 2417 BT 2418 Adastral Park, Martlesham Heath 2419 Ipswich IP5 3RE 2420 United Kingdom 2422 Email: trevor.burbridge@bt.com 2424 Philip Eardley 2425 BT 2426 Adastral Park, Martlesham Heath 2427 Ipswich IP5 3RE 2428 United Kingdom 2430 Email: philip.eardley@bt.com 2432 Marcelo Bagnulo 2433 Universidad Carlos III de Madrid 2434 Av. Universidad 30 2435 Leganes, Madrid 28911 2436 Spain 2438 Email: marcelo@it.uc3m.es 2440 Juergen Schoenwaelder 2441 Jacobs University Bremen 2442 Campus Ring 1 2443 Bremen 28759 2444 Germany 2446 Email: j.schoenwaelder@jacobs-university.de