idnits 2.17.1 draft-ietf-lmap-information-model-06.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 667 has weird spacing: '...ion-obj ma-su...' == Line 1026 has weird spacing: '...ask-obj ma-re...' == Line 1054 has weird spacing: '...row-obj ma-r...' == Line 1481 has weird spacing: '...dic-obj ma-ti...' == Line 1482 has weird spacing: '...dar-obj ma-ti...' == (2 more instances...) -- The document date (July 3, 2015) is 3220 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 (-14) exists of draft-ietf-lmap-framework-12 ** Downref: Normative reference to an Informational draft: draft-ietf-lmap-framework (ref. 'I-D.ietf-lmap-framework') == Outdated reference: A later version (-24) exists of draft-ietf-ippm-metric-registry-02 == Outdated reference: A later version (-12) exists of draft-ietf-lmap-yang-00 Summary: 1 error (**), 0 flaws (~~), 11 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: January 4, 2016 M. Bagnulo 6 Universidad Carlos III de Madrid 7 J. Schoenwaelder 8 Jacobs University Bremen 9 July 3, 2015 11 Information Model for Large-Scale Measurement Platforms (LMAP) 12 draft-ietf-lmap-information-model-06 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 MA or exists in 19 communications with a Controller or Collector within an LMAP 20 framework. The purpose of such an Information Model is to provide a 21 protocol and device independent view of the MA that can be 22 implemented via one or more Control and Report protocols. 24 Requirements Language 26 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 27 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 28 document are to be interpreted as described in RFC 2119 [RFC2119]. 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at http://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on January 4, 2016. 47 Copyright Notice 49 Copyright (c) 2015 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (http://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 65 2. Notation . . . . . . . . . . . . . . . . . . . . . . . . . . 4 66 3. LMAP Information Model . . . . . . . . . . . . . . . . . . . 4 67 3.1. Pre-Configuration Information . . . . . . . . . . . . . . 8 68 3.1.1. Definition of ma-preconfig-obj . . . . . . . . . . . 9 69 3.2. Configuration Information . . . . . . . . . . . . . . . . 10 70 3.2.1. Definition of ma-config-obj . . . . . . . . . . . . . 11 71 3.3. Instruction Information . . . . . . . . . . . . . . . . . 12 72 3.3.1. Definition of ma-instruction-obj . . . . . . . . . . 14 73 3.3.2. Definition of ma-suppression-obj . . . . . . . . . . 15 74 3.4. Logging Information . . . . . . . . . . . . . . . . . . . 16 75 3.4.1. Definition of ma-log-obj . . . . . . . . . . . . . . 17 76 3.5. Capability and Status Information . . . . . . . . . . . . 17 77 3.5.1. Definition of ma-status-obj . . . . . . . . . . . . . 18 78 3.5.2. Definition of ma-task-status-obj . . . . . . . . . . 18 79 3.5.3. Definition of ma-interface-obj . . . . . . . . . . . 19 80 3.6. Reporting Information . . . . . . . . . . . . . . . . . . 20 81 3.6.1. Definition of ma-report-obj . . . . . . . . . . . . . 22 82 3.6.2. Definition of ma-report-task-obj . . . . . . . . . . 23 83 3.6.3. Definition of ma-report-row-obj . . . . . . . . . . . 23 84 3.7. Common Objects: Schedules . . . . . . . . . . . . . . . . 24 85 3.7.1. Definition of ma-schedule-obj . . . . . . . . . . . . 25 86 3.7.2. Definition of ma-action-obj . . . . . . . . . . . . . 26 87 3.8. Common Objects: Channels . . . . . . . . . . . . . . . . 27 88 3.8.1. Definition of ma-channel-obj . . . . . . . . . . . . 28 89 3.9. Common Objects: Task Configurations . . . . . . . . . . . 28 90 3.9.1. Definition of ma-task-obj . . . . . . . . . . . . . . 30 91 3.9.2. Definition of ma-option-obj . . . . . . . . . . . . . 30 92 3.10. Common Objects: Event Information . . . . . . . . . . . . 31 93 3.10.1. Definition of ma-event-obj . . . . . . . . . . . . . 32 94 3.10.2. Definition of ma-periodic-obj . . . . . . . . . . . 33 95 3.10.3. Definition of ma-calendar-obj . . . . . . . . . . . 33 96 3.10.4. Definition of ma-one-off-obj . . . . . . . . . . . . 35 97 3.10.5. Definition of ma-immediate-obj . . . . . . . . . . . 35 98 3.10.6. Definition of ma-startup-obj . . . . . . . . . . . . 36 99 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 100 5. Security Considerations . . . . . . . . . . . . . . . . . . . 36 101 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 37 102 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 37 103 7.1. Normative References . . . . . . . . . . . . . . . . . . 37 104 7.2. Informative References . . . . . . . . . . . . . . . . . 37 105 Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . 37 106 Appendix B. Non-editorial Changes since -05 . . . . . . . . . . 38 107 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 38 109 1. Introduction 111 A large-scale measurement platform is a collection of components that 112 work in a coordinated fashion to perform measurements from a large 113 number of vantage points. The main components of a large-scale 114 measurement platform are the Measurement Agents (hereafter MAs), the 115 Controller(s) and the Collector(s). 117 The MAs are the elements actually performing the measurements. The 118 MAs are controlled by exactly one Controller at a time and the 119 Collectors gather the results generated by the MAs. In a nutshell, 120 the normal operation of a large-scale measurement platform starts 121 with the Controller instructing a set of one or more MAs to perform a 122 set of one or more Measurement Tasks at a certain point in time. The 123 MAs execute the instructions from a Controller, and once they have 124 done so, they report the results of the measurements to one or more 125 Collectors. The overall framework for a Large Measurement platform 126 as used in this document is described in detail in 127 [I-D.ietf-lmap-framework]. 129 A large-scale measurement platform involves basically three types of 130 protocols, namely, a Control protocol (or protocols) between a 131 Controller and the MAs, a Report protocol (or protocols) between the 132 MAs and the Collector(s) and several measurement protocols between 133 the MAs and Measurement Peers (MPs), used to actually perform the 134 measurements. In addition some information is required to be 135 configured on the MA prior to any communication with a Controller. 137 This document defines the information model for both Control and the 138 Report protocols along with pre-configuration information that is 139 required on the MA before communicating with the Controller, broadly 140 named as the LMAP Information Model. The measurement protocols are 141 out of the scope of this document. 143 As defined in [RFC3444], the LMAP Information Model defines the 144 concepts involved in a large-scale measurement platform at a high 145 level of abstraction, independent of any specific implementation or 146 actual protocol used to exchange the information. It is expected 147 that the proposed information model can be used with different 148 protocols in different measurement platform architectures and across 149 different types of MA devices (e.g., home gateway, smartphone, PC, 150 router). A YANG data model implementing the information model can be 151 found in [I-D.ietf-lmap-yang]. 153 The definition of an Information Model serves a number of purposes: 155 1. To guide the standardisation of one or more Control and Report 156 protocols and data models 158 2. To enable high-level inter-operability between different Control 159 and Report protocols by facilitating translation between their 160 respective data models such that a Controller could instruct sub- 161 populations of MAs using different protocols 163 3. To form agreement of what information needs to be held by an MA 164 and passed over the Control and Report interfaces and support the 165 functionality described in the LMAP framework 167 4. Enable existing protocols and data models to be assessed for 168 their suitability as part of a large-scale measurement system 170 2. Notation 172 This document uses a programming language-like notation to define the 173 properties of the objects of the information model. An optional 174 property is enclosed by square brackets, [ ], and a list property is 175 indicated by two numbers in angle brackets, , where m indicates 176 the minimal number of values, and n is the maximum. The symbol * for 177 n means no upper bound. 179 3. LMAP Information Model 181 The information described herein relates to the information stored, 182 received or transmitted by a Measurement Agent as described within 183 the LMAP framework [I-D.ietf-lmap-framework]. As such, some subsets 184 of this information model are applicable to the measurement 185 Controller, Collector and any device management system that pre- 186 configures the Measurement Agent. The information described in these 187 models will be transmitted by protocols using interfaces between the 188 Measurement Agent and such systems according to a Data Model. 190 For clarity the information model is divided into six sections: 192 1. Pre-Configuration Information. Information pre-configured on the 193 Measurement Agent prior to any communication with other 194 components of the LMAP architecture (i.e., the Controller, 195 Collector and Measurement Peers), specifically detailing how to 196 communicate with a Controller and whether the device is enabled 197 to participate as an MA. 199 2. Configuration Information. Update of the pre-configuration 200 information during the registration of the MA or subsequent 201 communication with the Controller, along with the configuration 202 of further parameters about the MA (rather than the Tasks it 203 should perform) that were not mandatory for the initial 204 communication between the MA and a Controller. 206 3. Instruction Information. Information that is received by the MA 207 from the Controller pertaining to the Tasks that should be 208 executed. This includes the task execution Schedules (other than 209 the Controller communication Schedule supplied as 210 (pre)configuration information) and related information such as 211 the Task Configuration, communication Channels to Collectors and 212 schedule Timing information. It also includes Task Suppression 213 information that is used to over-ride normal Task execution. 215 4. Logging Information. Information transmitted from the MA to the 216 Controller detailing the results of any configuration operations 217 along with error and status information from the operation of the 218 MA. 220 5. Capability and Status Information. Information on the general 221 status and capabilities of the MA. For example, the set of 222 measurements that are supported on the device. 224 6. Reporting Information. Information transmitted from the MA to 225 one or more Collectors including measurement results and the 226 context in which they were conducted. 228 In addition the MA may hold further information not described herein, 229 and which may be optionally transferred to or from other systems 230 including the Controller and Collector. One example of information 231 in this category is subscriber or line information that may be 232 extracted by a task and reported by the MA in the reporting 233 communication to a Collector. 235 It should also be noted that the MA may be in communication with 236 other management systems which may be responsible for configuring and 237 retrieving information from the MA device. Such systems, where 238 available, can perform an important role in transferring the pre- 239 configuration information to the MA or enabling/disabling the 240 measurement functionality of the MA. 242 The Information Model is divided into sub-sections for a number of 243 reasons. Firstly the grouping of information facilitates reader 244 understanding. Secondly, the particular groupings chosen are 245 expected to map to different protocols or different transmissions 246 within those protocols. 248 The granularity of data transmitted in each operation of the Control 249 and Report Protocols is not dictated by the Information Model. For 250 example, the Instruction object may be delivered in a single 251 operation. Alternatively, Schedules and Task Configurations may be 252 separated or even each Schedule/Task Configuration may be delivered 253 individually. Similarly the Information Model does not dictate 254 whether data is read, write, or read/write. For example, some 255 Control Protocols may have the ability to read back Configuration and 256 Instruction information which have been previously set on the MA. 257 Lastly, while some protocols may simply overwrite information (for 258 example refreshing the entire Instruction Information), other 259 protocols may have the ability to update or delete selected items of 260 information. 262 The information in these six sections is captured by a number of 263 common information objects. These objects are also described later 264 in this document and comprise of: 266 1. Schedules. A set of Schedules tell the MA to do something. 267 Without a Schedule no Task (from a measurement to reporting or 268 communicating with the Controller) is ever executed. Schedules 269 are used within the Instruction to specify what tasks should be 270 performed, when, and how to direct their results. A Schedule is 271 also used within the pre-Configuration and Configuration 272 information in order to execute the Task or Tasks required to 273 communicate with the Controller. 275 2. Channels. A set of Channel objects are used to communicate with 276 a number of endpoints (i.e., the Controller and Collectors). 277 Each Channel object contains the information required for the 278 communication with a single endpoint such as the target location 279 and security details. 281 3. Task Configurations. A set of Task Configurations is used to 282 configure the Tasks that are run by the MA. This includes the 283 registry entries for the Task and any configuration parameters. 284 Task Configurations are referenced from a Schedule in order to 285 specify what Tasks the MA should execute. 287 4. Events. A set of Event objects that can be referenced from the 288 Schedules. Each Schedule always references exactly one Event 289 object. An Event object specifies either a singleton or series 290 of events that indicate when Tasks should be executed. A 291 commonly used kind of Event objects are Timing objects. 293 Figure 1 illustrates the structure in which these common information 294 objects are referenced. The references are achieved by each object 295 (Task Configuration, Event) being given a short textual name that is 296 used by other objects. The objects shown in parenthesis are part of 297 the internal object structure of a Schedule. Channels are not shown 298 in the diagram since they are only used as an option by selected Task 299 Configurations but are similarly referenced using a short text name. 301 Schedule 302 |------> Event 303 |------> Action 1 304 | |------> Task Configuration 305 | `------> Destination Schedule 306 : 307 : 308 `------> Action N 309 |------> Task Configuration 310 `------> Destination Schedule 312 Figure 1: Relationship between Schedules, Events, Actions, Task 313 Configurations, and Destination Schedules 315 It should be clear that the top-level behavior of an MA is simply to 316 execute Schedules. Every Action referenced by a Schedule is defined 317 as a Task. As such, these Actions are configured through Task 318 Configurations and executed according to the Event object referenced 319 by the Schedule in which they appear. Note, however, that Actions 320 can have Action specific parameters. 322 Tasks can implement a variety of different types of actions. While 323 in terms of the Information Model, all Tasks have the same structure, 324 it can help conceptually to think of different Task categories: 326 1. Measurement Tasks measure some aspect of network performance or 327 traffic. They may also capture contextual information from the 328 MA device or network interfaces such as the device type or 329 interface speed. 331 2. Data Transfer Tasks 333 A. Reporting Tasks report the results of Measurement Tasks to 334 Collectors 336 B. Control Task(s) implement the Control Protocol and 337 communicate with the Controller. Depending on the Control 338 Protocol there may be a number of specialist tasks such as: 339 Configuration Task; Instruction Task; Suppression Task; 340 Capabilities Task; Logging Task etc. 342 3. Data Analysis Tasks can exist to analyse data from other 343 Measurement Tasks locally on the MA 345 4. Data Management Tasks may exist to clean-up, filter or compress 346 data on the MA such as Measurement Task results 348 Figure 1 indicates that Actions can produce data that is fed into 349 Destination Schedules. This can by used by Actions implementing 350 Measurement Tasks to feed measurement results to a Schedule that 351 triggers Actions implementing Reporting Tasks. 353 3.1. Pre-Configuration Information 355 This information is the minimal information that needs to be pre- 356 configured to the MA in order for it to successfully communicate with 357 a Controller during the registration process. Some of the Pre- 358 Configuration Information elements are repeated in the Configuration 359 Information in order to allow an LMAP Controller to update these 360 items. The pre-configuration information also contains some elements 361 that are not under the control of the LMAP framework (such as the 362 device identifier and device security credentials). 364 This Pre-Configuration Information needs to include a URL of the 365 initial Controller from where configuration information can be 366 communicated along with the security information required for the 367 communication including the certificate of the Controller (or the 368 certificate of the Certification Authority which was used to issue 369 the certificate for the Controller). All this is expressed as a 370 Channel. While multiple Channels may be provided in the Pre- 371 Configuration Information they must all be associated with a single 372 Controller (e.g., over different interfaces or network protocols). 374 Where the MA pulls information from the Controller, the Pre- 375 Configuration Information also needs to contain the timing of the 376 communication with the Controller as well as the nature of the 377 communication itself (such as the protocol and data to be 378 transferred). The timing is given as a Schedule that executes the 379 Task(s) responsible for communication with the Controller. It is 380 this Task (or Tasks) that implement the Control protocol between the 381 MA and the Controller and utilises the Channel information. The 382 Task(s) may take additional parameters in which case a Task 383 Configuration can also be included. 385 Even where information is pushed to the MA from the Controller 386 (rather than pulled by the MA), a Schedule still needs to be 387 supplied. In this case the Schedule will simply execute a Controller 388 listener task when the MA is started. A Channel is still required 389 for the MA to establish secure communication with the Controller. 391 It can be seen that these Channels, Schedules and Task Configurations 392 for the initial MA-Controller communication are no different in terms 393 of the Information Model to any other Channel, Schedule or Task 394 Configuration that might execute a Measurement Task or report the 395 measurement results (as described later). 397 The MA may be pre-configured with an MA ID, or may use a Device ID in 398 the first Controller contact before it is assigned an MA ID. The 399 Device ID may be a MAC address or some other device identifier 400 expressed as a URI. If the MA ID is not provided at this stage then 401 it must be provided by the Controller during Configuration. 403 3.1.1. Definition of ma-preconfig-obj 405 object { 406 [uuid ma-agent-id;] 407 ma-task-obj ma-control-tasks<1..*>; 408 ma-channel-obj ma-control-channels<1..*>; 409 ma-schedule-obj ma-control-schedules<1..*>; 410 [uri ma-device-id;] 411 credentials ma-credentials; 412 } ma-preconfig-obj; 414 The ma-preconfig-obj is essentially a subset of the ma-config-obj 415 described below. The ma-preconfig-obj consists of the following 416 elements: 418 ma-agent-id: An optional uuid uniquely identifying the 419 measurement agent. 421 ma-control-tasks: A collection of tasks objects. 423 ma-control-channels: A collection of channel objects. 425 ma-control-schedules: A collection of scheduling objects. 427 ma-device-id: An optional identifier for the device. 429 ma-credentials: The security credentials used by the 430 measurement agent. 432 3.2. Configuration Information 434 During registration or at any later point at which the MA contacts 435 the Controller (or vice-versa), the choice of Controller, details for 436 the timing of communication with the Controller or parameters for the 437 communication Task(s) can be changed (as captured by the Channels, 438 Schedules and Task Configurations objects). For example the pre- 439 configured Controller (specified as a Channel or Channels) may be 440 over-ridden with a specific Controller that is more appropriate to 441 the MA device type, location or characteristics of the network (e.g., 442 access technology type or broadband product). The initial 443 communication Schedule may be over-ridden with one more relevant to 444 routine communications between the MA and the Controller. 446 While some Control protocols may only use a single Schedule, other 447 protocols may use several Schedules (and related data transfer Tasks) 448 to update the Configuration Information, transfer the Instruction 449 Information, transfer Capability and Status Information and send 450 other information to the Controller such as log or error 451 notifications. Multiple Channels may be used to communicate with the 452 same Controller over multiple interfaces (e.g., to send logging 453 information over a different network). 455 In addition the MA will be given further items of information that 456 relate specifically to the MA rather than the measurements it is to 457 conduct or how to report results. The assignment of an ID to the MA 458 is mandatory. If the MA Agent ID was not optionally provided during 459 the pre-configuration then one must be provided by the Controller 460 during Configuration. Optionally a Group ID may also be given which 461 identifies a group of interest to which that MA belongs. For example 462 the group could represent an ISP, broadband product, technology, 463 market classification, geographic region, or a combination of 464 multiple such characteristics. Where the Measurement Group ID is set 465 an additional flag (the Report MA ID flag) is required to control 466 whether the Measurement Agent ID is also to be reported. The 467 reporting of a Group ID without the MA ID allows the MA to remain 468 anonymous, which may be particularly useful to prevent tracking of 469 mobile MA devices. 471 Optionally an MA can also be configured to stop executing any 472 Instruction Schedule if the Controller is unreachable. This can be 473 used as a fail-safe to stop Measurement and other Tasks being 474 conducted when there is doubt that the Instruction Information is 475 still valid. This is simply represented as a time window in seconds 476 since the last communication with the Controller after which 477 Instruction Schedules are to be suspended. The appropriate value of 478 the time window will depend on the specified communication Schedule 479 with the Controller and the duration for which the system is willing 480 to tolerate continued operation with potentially stale Instruction 481 Information. 483 While Pre-Configuration Information is persistent upon device reset 484 or power cycle, the persistency of the Configuration Information may 485 be device dependent. Some devices may revert back to their pre- 486 configuration state upon reboot or factory reset, while other devices 487 may store all Configuration and Instruction information in persistent 488 storage. A Controller can check whether an MA has the latest 489 Configuration and Instruction information by examining the Capability 490 and Status information for the MA. 492 It should be noted that control schedules and tasks cannot be 493 suppressed as evidenced by the lack of suppression information in the 494 Configuration. The control schedule must only reference tasks listed 495 as control tasks (i.e., within the Configuration information). Any 496 suppress-by-default flag against control tasks will be ignored. 498 3.2.1. Definition of ma-config-obj 500 object { 501 uuid ma-agent-id; 502 ma-task-obj ma-control-tasks<1..*>; 503 ma-channel-obj ma-control-channels<1..*>; 504 ma-schedule-obj ma-control-schedules<1..*>; 505 [uri ma-device-id;] 506 credentials ma-credentials; 507 [string ma-group-id;] 508 [boolean ma-report-agent-id;] 509 [int ma-controller-timeout;] 510 } ma-config-obj; 512 The ma-config-obj consists of the following elements: 514 ma-agent-id: A uuid uniquely identifying the measurement 515 agent. 517 ma-control-tasks: A collection of task objects. 519 ma-control-channels: A collection of channel objects. 521 ma-control-schedules: A collection of scheduling objects. 523 ma-device-id: An optional identifier for the device. 525 ma-credentials: The security credentials used by the 526 measurement agent. 528 ma-group-id: An optional identifier of the group of 529 measurement agents this measurement agent 530 belongs to. 532 ma-report-agent-id: An optional flag indicating whether the 533 identifier (ma-agent-id) should be included 534 in reports. 536 ma-controller-timeout: A timer is started after each successful 537 contact with a controller. When the timer 538 reaches the controller-timeout (measured in 539 seconds), all schedules will be disabled, 540 i.e., no new actions will be executed (and 541 hence no new tasks started). The disabled 542 schedules will be reenabled automatically 543 once contact with a controller has been 544 established successfully again. Note that 545 this will not affect the execution of 546 actions that are essential to establish 547 contact with the controller or that perform 548 critical housekeeping functions. 550 3.3. Instruction Information 552 The Instruction information model has four sub-elements: 554 1. Instruction Task Configurations 556 2. Report Channels 558 3. Instruction Schedules 560 4. Suppression 562 The Instruction supports the execution of all Tasks on the MA except 563 those that deal with communication with the Controller (specified in 564 (pre-)configuration information). The Tasks are configured in 565 Instruction Task Configurations and included by reference in 566 Instruction Schedules that specify when to execute them. The results 567 can be communicated to other Schedules or a Task may implement a 568 Reporting Protocol and communicate results over Report Channels. 569 Suppression is used to temporarily stop the execution of new Tasks as 570 specified by the Instruction Schedules (and optionally to stop 571 ongoing Tasks). 573 A Task Configuration is used to configure the mandatory and optional 574 parameters of a Task. It also serves to instruct the MA about the 575 Task including the ability to resolve the Task to an executable and 576 specifying the schema for the Task parameters. 578 A Report Channel defines how to communicate with a single remote 579 system specified by a URL. A Report Channel is used to send results 580 to single Collector but is no different in terms of the Information 581 Model to the Control Channel used to transfer information between the 582 MA and the Controller. Several Report Channels can be defined to 583 enable results to be split or duplicated across different 584 destinations. A single Channel can be used by multiple (reporting) 585 Task Configurations to transfer data to the same Collector. A single 586 Reporting Task Configuration can also be included in multiple 587 Schedules. E.g., a single Collector may receive data at three 588 different cycle rates, one Schedule reporting hourly, another 589 reporting daily and a third specifying that results should be sent 590 immediately for on-demand measurement tasks. Alternatively multiple 591 Report Channels can be used to send Measurement Task results to 592 different Collectors. The details of the Channel element is 593 described later as it is common to several objects. 595 Instruction Schedules specify which Actions to execute according to a 596 given triggering Event. An Action is a Task with additional specific 597 parameters. An Event can trigger the execution of a single Action or 598 it can trigger a repeated series of Actions. The Schedule also 599 specifies how to link Tasks output data to other Schedules. 601 Measurement Suppression information is used to over-ride the 602 Instruction Schedule and temporarily stop measurements or other Tasks 603 from running on the MA for a defined or indefinite period. While 604 conceptually measurements can be stopped by simply removing them from 605 the Measurement Schedule, splitting out separate information on 606 Measurement Suppression allows this information to be updated on the 607 MA on a different timing cycle or protocol implementation to the 608 Measurement Schedule. It is also considered that it will be easier 609 for a human operator to implement a temporary explicit suppression 610 rather than having to move to a reduced Schedule and then roll-back 611 at a later time. 613 The explicit Suppression instruction message is able to simply 614 enable/disable all Instruction Tasks (that are enabled for default 615 suppression) as well as having fine control on which Tasks are 616 suppressed. Suppression of both specified Task Configurations and 617 Measurement Schedules is supported. Support for disabling specific 618 Task Configurations allows malfunctioning or mis-configured Tasks or 619 Task Configurations that have an impact on a particular part of the 620 network infrastructure (e.g., a particular Measurement Peer) to be 621 targeted. Support for disabling specific Schedules allows for 622 particularly heavy cycles or sets of less essential Measurement Tasks 623 to be suppressed quickly and effectively. Note that Suppression has 624 no effect on either Controller Tasks or Controller Schedules. 626 When no tasks or schedules are explicitly listed, all Instruction 627 tasks will be suppressed (or not) as indicated by the suppress-by- 628 default flag in the Task Configuration. If tasks or schedules are 629 listed explicitly then only these listed tasks or schedules will be 630 suppressed regardless of the suppress-by-default flag. If both 631 individual tasks and individual schedules are listed then only the 632 listed schedules, plus the listed tasks where present in other 633 schedules, will be suppressed regardless of the suppress-by-default 634 flag. 636 Suppression stops new Tasks from executing. In addition, the 637 Suppression information also supports an additional Boolean that is 638 used to select whether on-going tasks are also to be terminated. 640 Unsuppression is achieved through either overwriting the Measurement 641 Suppression information (e.g., changing 'enabled' to False) or 642 through the use of an End time such that the Measurement Suppression 643 will no longer be in effect beyond this time. The datetime format 644 used for all elements in the information model (e.g., the suppression 645 start and end dates) MUST conform to RFC 3339 [RFC3339]. 647 The goal when defining these four different elements is to allow each 648 part of the information model to change without affecting the other 649 three elements. For example it is envisaged that the Report Channels 650 and the set of Task Configurations will be relatively static. The 651 Instruction Schedule, on the other hand, is likely to be more 652 dynamic, as the measurement panel and test frequency are changed for 653 various business goals. Another example is that measurements can be 654 suppressed with a Suppression command without removing the existing 655 Instruction Schedules that would continue to apply after the 656 Suppression expires or is removed. In terms of the Controller-MA 657 communication this can reduce the data overhead. It also encourages 658 the re-use of the same standard Task Configurations and Reporting 659 Channels to help ensure consistency and reduce errors. 661 3.3.1. Definition of ma-instruction-obj 663 object { 664 ma-task-obj ma-instruction-tasks<0..*>; 665 ma-channel-obj ma-report-channels<0..*>; 666 ma-schedule-obj ma-instruction-schedules<0..*>; 667 ma-suppression-obj ma-suppression; 668 } ma-instruction-obj; 670 An ma-instruction-obj consists of the following elements: 672 ma-task-obj: A possibly empty collection of task objects. 674 ma-channel-obj: A possibly empty collection of channel objects. 676 ma-schedule-obj: A possibly empty collection of schedule objects. 678 ma-suppression-obj: A suppression object. 680 3.3.2. Definition of ma-suppression-obj 682 object { 683 boolean ma-suppression-enabled; 684 [boolean ma-suppression-stop-running;] 685 [datetime ma-suppression-start;] 686 [datetime ma-suppression-end;] 687 [string ma-suppression-task-names<0..*>;] 688 [string ma-suppression-schedule-names<0..*>;] 689 } ma-suppression-obj; 691 The ma-suppression-obj consists of the following elements: 693 ma-suppression-enabled: A boolean indicating whether 694 suppression is enabled or not. The 695 default value is false. 697 ma-suppression-stop-running: An optional boolean indicating 698 whether suppression will stop any 699 running tasks. The default value for 700 this boolean is false. 702 ma-suppression-start: The optional date and time when 703 suppression starts. The default 704 value is 'immediate'. 706 ma-suppression-end: The optional date and time when 707 suppression ends. The default value 708 is 'indefinite'. 710 ma-suppression-task-names: An optional and possibly empty 711 collection of task names. If not 712 present, this defaults to all tasks. 714 ma-suppression-schedule-names: An optional and possibly empty 715 collection of schedule names. If not 716 present, this defaults to all 717 schedules. 719 3.4. Logging Information 721 The MA may report on the success or failure of Configuration or 722 Instruction communications from the Controller. In addition further 723 operational logs may be produced during the operation of the MA and 724 updates to capabilities may also be reported. Reporting this 725 information is achieved in exactly the same manner as scheduling any 726 other Task. We make no distinction between a Measurement Task 727 conducting an active or passive network measurement and one which 728 solely retrieves static or dynamic information from the MA such as 729 capabilities or logging information. One or more logging tasks can 730 be programmed or configured to capture subsets of the Logging 731 Information. These logging tasks are then executed by Schedules 732 which also specify that the resultant data is to be transferred over 733 the Controller Channels. 735 The type of Logging Information will fall into three different 736 categories: 738 1. Success/failure/warning messages in response to information 739 updates from the Controller. Failure messages could be produced 740 due to some inability to receive or parse the Controller 741 communication, or if the MA is not able to act as instructed. 742 For example: 744 * "Measurement Schedules updated OK" 746 * "Unable to parse JSON" 748 * "Missing mandatory element: Measurement Timing" 750 * "'Start' does not conform to schema - expected datetime" 752 * "Date specified is in the past" 754 * "'Hour' must be in the range 1..24" 756 * "Schedule A refers to non-existent Measurement Task 757 Configuration" 759 * "Measurement Task Configuration X registry entry Y not found" 761 * "Updated Measurement Task Configurations do not include M used 762 by Measurement Schedule N" 764 2. Operational updates from the MA. For example: 766 * "Out of memory: cannot record result" 767 * "Collector 'collector.example.com' not responding" 769 * "Unexpected restart" 771 * "Suppression timeout" 773 * "Failed to execute Measurement Task Configuration H" 775 3. Status updates from the MA. For example: 777 * "Device interface added: eth3" 779 * "Supported measurements updated" 781 * "New IP address on eth0: xxx.xxx.xxx.xxx" 783 This Information Model document does not detail the precise format of 784 logging information since it is to a large extent protocol and MA 785 specific. However, some common information can be identified. 787 3.4.1. Definition of ma-log-obj 789 object { 790 uuid ma-log-agent-id; 791 datetime ma-log-event-time; 792 code ma-log-code; 793 string ma-log-description; 794 } ma-log-obj; 796 The ma-log-obj models the generic aspects of a logging object and 797 consists of the following elements: 799 ma-log-agent-id: A uuid uniquely identifying the measurement 800 agent. 802 ma-log-event-time: The date and time of the event reported in 803 the logging object. 805 ma-log-code: A machine readable code describing the 806 event. 808 ma-log-description: A human readable description of the event. 810 3.5. Capability and Status Information 812 The MA will hold Capability Information that can be retrieved by a 813 Controller. Capabilities include the device interface details 814 available to Measurement Tasks as well as the set of Measurement 815 Tasks/Roles (specified by registry entries) that are actually 816 installed or available on the MA. Status information includes the 817 times that operations were last performed such as contacting the 818 Controller or producing Reports. 820 3.5.1. Definition of ma-status-obj 822 object { 823 uuid ma-agent-id; 824 uri ma-device-id; 825 string ma-hardware; 826 string ma-firmware; 827 string ma-version; 828 ma-interface-obj ma-interfaces<0..*>; 829 datetime ma-last-started; 830 [ma-task-status-obj ma-task-status<0..*>;] 831 } ma-status-obj; 833 The ma-status-obj provides status information about the measurement 834 agent and consists of the following elements: 836 ma-agent-id: A uuid uniquely identifying the measurement 837 agent. 839 ma-device-id: A URI identifying the device. 841 ma-hardware: A description of the hardware of the device 842 the measurement agent is running on. 844 ma-firmware: A description of the firmware of the device 845 the measurement agent is running on. 847 ma-version: The version of the measurement agent. 849 ma-interfaces: A list of network interfaces available on 850 the device. 852 ma-last-started: The date and time the measurement agent 853 last started. 855 ma-task-status: An optional list of status objects for each 856 supported task. 858 3.5.2. Definition of ma-task-status-obj 859 object { 860 string ma-task-name; 861 uri ma-task-registry-entries<1..*>; 862 [string ma-task-role<0..*>;] 863 datetime ma-task-last-invocation; 864 datetime ma-task-last-completion; 865 int ma-task-last-status; 866 string ma-task-last-message; 867 datetime ma-task-last-failed-completion; 868 int ma-task-last-failed-status; 869 string ma-task-last-failed-message; 870 } ma-task-status-obj; 872 The ma-task-status-obj provides status information about a task and 873 consists of the following elements: 875 ma-task-name: A name uniquely identifying a task. 877 ma-task-registry-entries: A possibly empty list of URIs 878 identifying the metrics a measurement 879 task supports. 881 ma-task-role: An optional and possibly empty list 882 of roles of a task. 884 ma-task-last-completion: The date and time of the last 885 completion of this task. 887 ma-task-last-status: The status code returned by the last 888 execution of this task. 890 ma-task-last-message: The status message produced by the 891 last execution of this task. 893 ma-task-last-failed-completion: The date and time of the last failed 894 completion of this task. 896 ma-task-last-failed-status: The status code returned by the last 897 failed execution of this task. 899 ma-task-last-failed-message: The status message produced by the 900 last failed execution of this task. 902 3.5.3. Definition of ma-interface-obj 903 object { 904 string ma-interface-name; 905 string ma-interface-type; 906 [int ma-interface-speed;] 907 [string ma-interface-link-layer-address;] 908 [ip-address ma-interface-ip-addresses<0..*>]; 909 [ip-address ma-interface-gateways<0..*>;] 910 [ip-address ma-interface-dns-servers<0..*>;] 911 } ma-interface-obj; 913 The ma-interface-obj provides status information about network 914 interfaces and consists of the following elements: 916 ma-interface-name: A name uniquely identifying a 917 network interface. 919 ma-interface-type: The type of the network interface. 921 ma-interface-speed: An optional indication of the speed 922 of the interface (measured in bits- 923 per-second). 925 ma-interface-link-layer-address: An optional link-layer address of 926 the interface. 928 ma-interface-ip-addresses: An optional list of IP addresses 929 assigned to the interface. 931 ma-interface-gateways: An optional list of gateways 932 assigned to the interface. 934 ma-interface-dns-servers: An optional list of DNS servers 935 assigned to the interface. 937 3.6. Reporting Information 939 At a point in time specified by a Schedule, the MA will execute a 940 task or tasks that communicate a set of measurement results to the 941 Collector. These Reporting Tasks will be configured to transmit task 942 results over a specified Report Channel to a Collector. 944 It should be noted that the output from Tasks does not need to be 945 sent to communication Channels. It can alternatively, or 946 additionally, be sent to other Tasks on the MA. This facilitates 947 using a first Measurement Task to control the operation of a later 948 Measurement Task (such as first probing available line speed and then 949 adjusting the operation of a video testing measurement) and also to 950 allow local processing of data to output alarms (e.g., when 951 performance drops from earlier levels). Of course, subsequent Tasks 952 also include Tasks that implement the reporting protocol(s) and 953 transfer data to one or more Collector(s). 955 The Report generated by a Reporting Task is structured hierarchically 956 to avoid repetition of report header and Measurement Task 957 Configuration information. The report starts with the timestamp of 958 the report generation on the MA and details about the MA including 959 the optional Measurement Agent ID and Group ID (controlled by the 960 Configuration Information). 962 Much of the report Information is optional and will depend on the 963 implementation of the Reporting Task and any parameters defined in 964 the Task Configuration for the Reporting Task. For example some 965 Reporting Tasks may choose not to include the Measurement Task 966 Configuration or scheduled task parameters, while others may do so 967 dependent on the Controller setting a configurable parameter in the 968 Task Configuration. 970 It is possible for a Reporting Task to send just the Report header 971 (datetime and optional agent ID and/or Group ID) if no measurement 972 data is available. Whether to send such empty reports again is 973 dependent on the implementation of the Reporting Task and potential 974 Task Configuration parameter. 976 The handling of measurement data on the MA before generating a Report 977 and transfer from the MA to the Collector is dependent on the 978 implementation of the device, MA and/or scheduled Tasks and not 979 defined by the LMAP standards. Such decisions may include limits to 980 the measurement data storage and what to do when such available 981 storage becomes depleted. 983 No context information, such as line speed or broadband product are 984 included within the report header information as this data is 985 reported by individual tasks at the time they execute. Either a 986 Measurement Task can report contextual parameters that are relevant 987 to that particular measurement, or specific tasks can be used to 988 gather a set of contextual and environmental data. at certain times 989 independent of the reporting schedule. 991 After the report header information the results are reported grouped 992 according to different Measurement Task Configurations. Each Task 993 section optionally starts with replicating the Measurement Task 994 Configuration information before the result headers (titles for data 995 columns) and the result data rows. The Options reported are those 996 used for the scheduled execution of the Measurement Task and 997 therefore include the Options specified in the Task Configuration as 998 well as additional Options specified in the Scheduled Task. The 999 Scheduled Task Options are appended to the Task Configuration Options 1000 in exactly the same order as they were provided to the Task during 1001 execution. 1003 The result row data includes a time for the start of the measurement 1004 and optionally an end time where the duration also needs to be 1005 considered in the data analysis. 1007 Some Measurement Tasks may optionally include an indication of the 1008 cross-traffic although the definition of cross-traffic is left up to 1009 each individual Measurement Task. Some Measurement Tasks may also 1010 output other environmental measures in addition to cross-traffic such 1011 as CPU utlilisation or interface speed. 1013 Where the Configuration and Instruction information represent 1014 information transmitted via the Control Protocol, the Report 1015 represents the information that is transmitted via the Report 1016 Protocol. It is constructed at the time of sending a report and 1017 represents the inherent structure of the information that is sent to 1018 the Collector. 1020 3.6.1. Definition of ma-report-obj 1022 object { 1023 datetime ma-report-date; 1024 [uuid ma-report-agent-id;] 1025 [string ma-report-group-id;] 1026 [ma-report-task-obj ma-report-tasks<0..*>]; 1027 } ma-report-obj; 1029 The ma-report-obj provides the meta-data of a single report and 1030 consists of the following elements: 1032 ma-report-date: The date and time when the report was sent 1033 to a collector. 1035 ma-report-agent-id: An optional uuid uniquely identifying the 1036 measurement agent. 1038 ma-report-group-id: An optional identifier of the group of 1039 measurement agents this measurement agent 1040 belongs to. 1042 ma-report-tasks: An optional and possibly empty list of 1043 tasks result objects. 1045 3.6.2. Definition of ma-report-task-obj 1047 object { 1048 string ma-report-task-name; 1049 [uri ma-report-task-registry-entries<1..*>;] 1050 [ma-option-obj ma-report-task-options<0..*>]; 1051 [ma-option-obj ma-report-task-action-options<0..*>]; 1052 [string ma-report-task-cycle-id;] 1053 [string ma-report-task-column-labels<0..*>;] 1054 [ma-report-row-obj ma-report-task-rows<0..*>;] 1055 } ma-report-task-obj; 1057 The ma-report-task-obj provides the meta-data of a result report of a 1058 single task. It consists of the following elements: 1060 ma-report-task-name: A name uniquely identifying the 1061 task that produced the results 1062 being reported. 1064 ma-report-task-registry-entries: An optional possibly empty list of 1065 URIs identifying the metrics 1066 reported. 1068 ma-report-task-options: An optional list of task options 1069 provided by the task object. 1071 ma-report-task-action-options: An optional list of action options 1072 provided by the scheduling object. 1074 ma-report-task-cycle-id: An optional measurement cycle 1075 identifier. 1077 ma-report-task-column-labels: An optional and possibly empty list 1078 of column labels. 1080 ma-report-task-rows: An optional and possibly empty list 1081 of result rows. 1083 3.6.3. Definition of ma-report-row-obj 1085 object { 1086 datetime ma-report-result-start-time; 1087 [datetime ma-report-result-end-time;] 1088 string ma-report-result-conflicts<0..*>; 1089 data ma-report-result-values<0..*>; 1090 } ma-report-row-obj; 1092 The ma-report-row-obj represents a result row and consists of the 1093 following elements: 1095 ma-report-result-start-time: The date and time of the start of the 1096 measurement task that produced the 1097 reported result values. 1099 ma-report-result-end-time: An optional date and time indicating 1100 when the measurement task that produced 1101 the reported result values finished. 1103 ma-report-result-conflicts: A possibly empty set of names of task 1104 that might have impacted the 1105 measurement being reported. 1107 ma-report-result-values: A possibly empty set of result values. 1108 When present, it contains an ordered 1109 set of values that align to the set of 1110 column labels for the report. 1112 3.7. Common Objects: Schedules 1114 A Schedule specifies the execution of a single or repeated series of 1115 Actions. An Action is a Task with additional specific parameters. 1116 Each Schedule contains basically two elements: a list of Actions to 1117 be executed and an Event object for the Schedule. The Schedule 1118 states what Actions to run (with what configuration) and when to run 1119 the Actions. 1121 Multiple Actions in the list of a single Measurement Schedule will be 1122 executed according to the execution mode of the Schedule. In 1123 sequential mode, Actions will be executed sequentially and in 1124 parallel mode, all Actions will be executed concurrently. In 1125 pipelined mode, data produced by one Action is passed to the 1126 subsequent Action. Actions in different Schedules execute in 1127 parallel with such conflicts being reported in the Reporting 1128 Information where necessary. If two or more Schedules have the same 1129 start time, then the two will execute in parallel. There is no 1130 mechanism to prioritise one schedule over another or to mutex 1131 scheduled tasks. 1133 As well as specifying which Actions to execute, the Schedule also 1134 specifies how to link the data outputs from each Action to other 1135 Schedules. Specifying this within the Schedule allows the highest 1136 level of flexibility since it is even possible to send the output 1137 from different executions of the same Task Configuration to different 1138 destinations. A single Task producing multiple different outputs is 1139 expected to properly tag the different result. An Action receiving 1140 the output can then filter the results based on the tag if necessary. 1141 For example, a Measurement Task might report routine results to a 1142 data Reporting Task in a Schedule that communicates hourly via the 1143 Broadband PPP interface, but also outputs emergency conditions via an 1144 alarm Reporting Task in a different Schedule communicating 1145 immediately over a GPRS channel. Note that task-to-task data 1146 transfer is always specified in association with the scheduled 1147 execution of the sending task - there is no need for a corresponding 1148 input specification for the receiving task. While it is likely that 1149 an MA implementation will use a queue mechanism between the Schedules 1150 or Actions, this Information Model does not mandate or define a 1151 queue, or any potential associated parameters such as storage size 1152 and retention policies. 1154 When specifying the task to execute within the Schedule, i.e., 1155 creating an Action, it is possible to add to the task configuration 1156 option parameters. This allows the Task Configuration to determine 1157 the common characteristics of a Task, while selected parameters 1158 (e.g., the test target URL) are defined within the schedule. A 1159 single Tasks Configuration can even be used multiple times in the 1160 same schedule with different additional parameters. This allows for 1161 efficiency in creating and transferring the Instruction. Note that 1162 the semantics of what happens if an option is defined multiple times 1163 (either in the Task Configuration, Schedule or in both) is not 1164 standardised and will depend upon the Task. For example, some tasks 1165 may legitimately take multiple values for a single parameter. 1167 Where Options are specified in both the Schedule and the Task 1168 Configuration, the Schedule Options are appended to those specified 1169 in the Task Configuration. 1171 Example: An Action of a Schedule references a single Measurement 1172 Task Configuration for measuring UDP latency. It specifies that 1173 results are to be sent to a Schedule with a Reporting Action. 1174 This Reporting Task of the Reporting Action is executed by a 1175 separate Schedule that specifies that it should run hourly at 5 1176 minutes past the hour. When run this Reporting Action takes the 1177 data generated by the UDP latency Measurement Task as well as any 1178 other data to be included in the hourly report and transfers it to 1179 the Collector over the Report Channel specified within its own 1180 Schedule. 1182 3.7.1. Definition of ma-schedule-obj 1183 object { 1184 string ma-schedule-name; 1185 ma-event-obj ma-schedule-event; 1186 ma-action-obj ma-schedule-actions<0..*>; 1187 string ma-schedule-execution-mode; 1188 } ma-schedule-obj; 1190 The ma-schedule-obj is the main scheduling object. It consists of 1191 the following elements: 1193 ma-schedule-name: A name uniquely identifying a scheduling 1194 object. 1196 ma-schedule-event: An event object indicating when the 1197 schedule fires. 1199 ma-schedule-actions: A possibly empty list of actions to 1200 invoke when the schedule fires. 1202 ma-schedule-execution-mode: Indicates whether the actions should be 1203 executed sequentially, in parallel, or in 1204 a pipelined mode (where data produced by 1205 one action is passed to the subsequent 1206 action). 1208 3.7.2. Definition of ma-action-obj 1210 object { 1211 string ma-action-name; 1212 string ma-action-task-name; 1213 [ma-option-obj ma-action-task-options<0..*>]; 1214 [string ma-action-destinations<0..*>;] 1215 } ma-action-obj; 1217 The ma-action-obj models an a task together with its schedule 1218 specific options and destination tasks. It consists of the following 1219 elements: 1221 ma-action-name: A name uniquely identifying an action of a 1222 scheduling object. 1224 ma-action-task-name: A name identifying the task to be invoked 1225 by the action. 1227 ma-action-task-options: An optional and possibly empty list of 1228 options (name-value pairs) that are passed 1229 to the task by appending them to the 1230 options configured for the task object. 1232 ma-action-destinations: An optional and possibly empty list of 1233 names of destination schedules that consume 1234 output produced by this action. 1236 3.8. Common Objects: Channels 1238 A Channel defines a bi-directional communication channel between the 1239 MA and a Controller or Collector. Multiple Channels can be defined 1240 to enable results to be split or duplicated across different 1241 Collectors. 1243 Each Channel contains the details of the remote endpoint (including 1244 location and security credential information such as the 1245 certificate). The timing of when to communicate over a Channel is 1246 specified by the Schedule which executes the corresponding Control or 1247 Reporting Task. The certificate can be the digital certificate 1248 associated to the FQDN in the URL or it can be the certificate of the 1249 Certification Authority that was used to issue the certificate for 1250 the FQDN (Fully Qualified Domain Name) of the target URL (which will 1251 be retrieved later on using a communication protocol such as TLS). 1252 In order to establish a secure channel, the MA will use it's own 1253 security credentials (in the Configuration Information) and the given 1254 credentials for the individual Channel end-point. 1256 As with the Task Configurations, each Channel is also given a text 1257 name by which it can be referenced as a Task Option. 1259 Although the same in terms of information, Channels used for 1260 communication with the Controller are referred to as Control Channels 1261 whereas Channels to Collectors are referred to as Report Channels. 1262 Hence Control Channels will be referenced from Control Tasks executed 1263 by a Control Schedule, whereas Report Channels will be referenced 1264 from within Reporting Tasks executed by an Instruction Schedule. 1266 Multiple interfaces are also supported. For example the Reporting 1267 Task could be configured to send some results over GPRS. This is 1268 especially useful when such results indicate the loss of connectivity 1269 on a different network interface. 1271 Example: A Channel used for reporting results may specify that 1272 results are to be sent to the URL (https://collector.example.org/ 1273 report/), using the appropriate digital certificate to establish a 1274 secure channel.. 1276 3.8.1. Definition of ma-channel-obj 1278 object { 1279 string ma-channel-name; 1280 url ma-channel-target; 1281 credentials ma-channel-credentials; 1282 [string ma-channel-interface-name;] 1283 } ma-channel-obj; 1285 The ma-channel-obj consists of the following elements: 1287 ma-channel-name: A unique name identifying the channel 1288 object. 1290 ma-channel-target: A URL identifying the target channel 1291 endpoint. 1293 ma-channel-credentials: The security credentials needed to 1294 establish a secure channel. 1296 ma-channel-interface-name: An optional name of the network interface 1297 to be used. If not present, the system 1298 will select a suitable interface. 1300 3.9. Common Objects: Task Configurations 1302 Conceptually each Task Configuration defines the parameters of a Task 1303 that the Measurement Agent (MA) may perform at some point in time. 1304 It does not by itself actually instruct the MA to perform them at any 1305 particular time (this is done by a Schedule). Tasks can be 1306 Measurement Tasks (i.e., those Tasks actually performing some type of 1307 passive or active measurement) or any other scheduled activity 1308 performed by the MA such as transferring information to or from the 1309 Controller and Collectors. Other examples of Tasks may include data 1310 manipulation or processing Tasks conducted on the MA. 1312 A Measurement Task Configuration is the same in information terms to 1313 any other Task Configuration. Both measurement and non-measurement 1314 Tasks have registry entries to enable the MA to uniquely identify the 1315 Task it should execute and retrieve the schema for any parameters 1316 that may be passed to the Task. Registry entries are specified as a 1317 URI and can therefore be used to identify the Task within a namespace 1318 or point to a web or local file location for the Task information. 1319 As mentioned previously, these URIs may be used to identify the 1320 Measurement Task in a public namespace 1321 [I-D.ietf-ippm-metric-registry]. 1323 Example: A Measurement Task Configuration may configure a single 1324 Measurement Task for measuring UDP latency. The Measurement Task 1325 Configuration could define the destination port and address for 1326 the measurement as well as the duration, internal packet timing 1327 strategy and other parameters (for example a stream for one hour 1328 and sending one packet every 500 ms). It may also define the 1329 output type and possible parameters (for example the output type 1330 can be the 95th percentile mean) where the measurement task 1331 accepts such parameters. It does not define when the task starts 1332 (this is defined by the Schedule element), so it does not by 1333 itself instruct the MA to actually perform this Measurement Task. 1335 The Task Configuration will include a local short name for reference 1336 by a Schedule. Task Configurations may also refer to registry 1337 entries as described above. In addition the Task can be configured 1338 through a set of configuration Options. The nature and number of 1339 these Options will depend upon the Task. These options are expressed 1340 as name-value pairs although the 'value' may be a structured object 1341 instead of a simple string or numeric value. The implementation of 1342 these name-value pairs will vary between data models. 1344 An Option that must be present for Reporting Tasks is the Channel 1345 reference specifying how to communicate with a Collector. This is 1346 included in the task options and will have a value that matches a 1347 channel name that has been defined in the Instruction. Similarly 1348 Control Tasks will have a similar option with the value set to a 1349 specified Control Channel. 1351 A reporting task might also have a flag parameter to indicate whether 1352 to report if there is no measurement result data pending to be 1353 transferred to the Collector. In addition many tasks will also take 1354 as a parameter which interface to operate over. 1356 The Task Configuration also contains a suppress-by-default flag that 1357 specifies the behaviour of a default suppress instruction (that does 1358 not list explicit tasks or schedules). If this flag is set to FALSE 1359 then the Task will not be suppressed. It should be noted that 1360 Controller Tasks are not subject to the suppression instruction and 1361 therefore this flag will be ignored in such cases. 1363 In addition the Task Configuration may optionally also be given a 1364 Measurement Cycle ID. The purpose of this ID is to easily identify a 1365 set of measurement results that have been produced by Measurement 1366 Tasks with comparable Options. This ID could be manually incremented 1367 or otherwise changed when an Option change is implemented which could 1368 mean that two sets of results should not be directly compared. 1370 3.9.1. Definition of ma-task-obj 1372 object { 1373 string ma-task-name; 1374 uri ma-task-registry-entries<1..*>; 1375 [ma-option-obj ma-task-options<0..*>]; 1376 [boolean ma-task-suppress-by-default;] 1377 [string ma-task-cycle-id;] 1378 } ma-task-obj; 1380 The ma-task-obj defines a task that can be invoked. A task can be 1381 referenced by its name and it contains a set of URIs to link to a 1382 metrics registry or a local specification of the task. Options allow 1383 the configuration of task parameter (in the form of name-value 1384 pairs). The ma-task-obj consists of the following elements: 1386 ma-task-name: A name uniquely identifying a task 1387 object. 1389 ma-task-registry-entries: A possibly empty list of URIs 1390 identifying the metrics a measurement 1391 task supports. 1393 ma-task-options: A optional and possibly empty list of 1394 options (name-value pairs) that are 1395 passed to the task. 1397 ma-task-suppress-by-default: A boolean flag indicating whether the 1398 task will be suppressed by default. 1399 The default value of the flag is true. 1401 ma-task-cycle-id: An optional measurement cycle 1402 identifier that can be used to identify 1403 set of measurement results that have 1404 been produced by tasks with comparable 1405 options. 1407 3.9.2. Definition of ma-option-obj 1409 object { 1410 string ma-option-name; 1411 [object ma-option-value;] 1412 } ma-option-obj; 1414 The ma-option-obj models a name-value pair and consists of the 1415 following elements: 1417 ma-option-name: The name of the option. 1419 ma-option-value: The optional value of the option. 1421 While many of the Task Configuration Options are left to individual 1422 tasks to define, some common Options are used by multiple tasks and 1423 benefit from standardisation. These Options are Channel and Role. 1425 o Channel is used to specify the details of an endpoint for Control 1426 or Reporting Task communications and is detailed elsewhere in this 1427 document. The common option name for specifying the channel is 1428 "channel". 1430 o Role is used to specify which Role the task should be performing 1431 (as defined in the registry) if multiple roles are available. The 1432 common option name for specifying the role is "role". 1434 3.10. Common Objects: Event Information 1436 The Event information object used throughout the information models 1437 can initially take one of five different forms. Additional forms may 1438 be defined later in order to bind the execution of schedules to 1439 additional events. The initially defined five Event forms are: 1441 1. Periodic Timing: Emits multiple events periodically according to 1442 an interval time defined in milliseconds 1444 2. Calendar Timing: Emits multiple events according to a calendar 1445 based pattern, e.g., 22 minutes past each hour of the day on 1446 weekdays 1448 3. One Off Timing: Emits one event at a specific date and time 1450 4. Immediate: Emits one event as soon as possible 1452 5. Startup: Emits an event whenever the MA is started (e.g., at 1453 device startup) 1455 Optionally each of the Event options may also specify a randomness 1456 that should be evaluated and applied separately to each indicated 1457 event. This randomness parameter defines a uniform interval in 1458 milliseconds over which the start of the task is delayed from the 1459 starting times specified by the timing object. 1461 Both the Periodic and Calendar timing objects allow for a series of 1462 Actions to be executed. While both have an optional end time, it is 1463 best practice to always configure an end time and refresh the 1464 information periodically to ensure that lost MAs do not continue 1465 their tasks forever. 1467 Startup events are only created on device startup, not when a new 1468 Instruction is transferred to the MA. If scheduled task execution is 1469 desired both on the transfer of the Instruction and on device restart 1470 then both the Immediate and Startup timing needs to be used in 1471 conjunction. 1473 The datetime format used for all elements in the information model 1474 MUST conform to RFC 3339 [RFC3339]. 1476 3.10.1. Definition of ma-event-obj 1478 object { 1479 string ma-event-name; 1480 union { 1481 ma-periodic-obj ma-timing-periodic; 1482 ma-calendar-obj ma-timing-calendar; 1483 ma-one-off-obj ma-timing-one-off; 1484 ma-immediate-obj ma-event-immediate; 1485 ma-startup-obj ma-event-startup; 1486 } 1487 [int ma-event-random-spread;] 1488 } ma-event-obj; 1490 The ma-event-obj is the main event object. Event objects are 1491 identified by a name. The generic event object itself contains a 1492 more specific event object and the set of specific event objects 1493 should be extensible. These five initial specific event objects are 1494 further described below. The ma-event-obj also includes an optional 1495 uniform random spread in milliseconds that can be used to randomize 1496 the start times of scheduled tasks. The ma-event-obj consists of the 1497 following elements: 1499 ma-timing-name: The name uniquely identifies an event 1500 object. Schedules refer to event objects 1501 by this name. 1503 ma-timing-periodic: The ma-timing-periodic is present for 1504 periodic timing objects. 1506 ma-timing-calendar: The ma-timing-calendar is present for 1507 calendar timing objects. 1509 ma-timing-one-off: The ma-timing-one-off is present for one- 1510 off timing objects. 1512 ma-timing-immediate: The ma-event-immediate is present for 1513 immediate event objects. 1515 ma-timing-startup: The ma-event-startup is present for startup 1516 event objects. 1518 ma-timing-random-spread: The optional ma-event-random-spread adds a 1519 random delay defined in milliseconds to the 1520 event object. 1522 3.10.2. Definition of ma-periodic-obj 1524 object { 1525 [datetime ma-periodic-start;] 1526 [datetime ma-periodic-end;] 1527 int ma-periodic-interval; 1528 } ma-periodic-obj; 1530 The ma-periodic-obj timing object has an optional start and an 1531 optional end time plus a periodic interval. Schedules using an ma- 1532 periodic-obj are started periodically between the start and end time. 1533 The ma-periodic-obj consists of the following elements: 1535 ma-periodic-start: The optional date and time at which 1536 Schedules using this object are first 1537 started. If not present it defaults to 1538 immediate. 1540 ma-periodic-end: The optional date and time at which 1541 Schedules using this object are last 1542 started. If not present it defaults to 1543 indefinite. 1545 ma-periodic-interval: The interval defines the time in 1546 milliseconds between two consecutive starts 1547 of tasks. 1549 3.10.3. Definition of ma-calendar-obj 1551 Calendar Timing supports the routine execution of Actions at specific 1552 times and/or on specific dates. It can support more flexible timing 1553 than Periodic Timing since the execution of Actions does not have to 1554 be uniformly spaced. For example a Calendar Timing could support the 1555 execution of a Measurement Task every hour between 6pm and midnight 1556 on weekdays only. 1558 Calendar Timing is also required to perform measurements at 1559 meaningful times in relation to network usage (e.g., at peak times). 1560 If the optional timezone offset is not supplied then local system 1561 time is assumed. This is essential in some use cases to ensure 1562 consistent peak-time measurements as well as supporting MA devices 1563 that may be in an unknown timezone or roam between different 1564 timezones (but know their own timezone information such as through 1565 the mobile network). 1567 The calendar elements within the Calendar Timing do not have defaults 1568 in order to avoid accidental high-frequency execution of Tasks. If 1569 all possible values for an element are desired then the wildcard * is 1570 used. 1572 object { 1573 [datetime ma-calendar-start;] 1574 [datetime ma-calendar-end;] 1575 [string ma-calendar-months<0..*>;] 1576 [string ma-calendar-days-of-week<0..*>;] 1577 [string ma-calendar-days-of-month<0..*>;] 1578 [string ma-calendar-hours<0..*>;] 1579 [string ma-calendar-minutes<0..*>;] 1580 [string ma-calendar-seconds<0..*>;] 1581 [int ma-calendar-timezone-offset;] 1582 } ma-calendar-obj; 1584 ma-calendar-start: The optional date and time at which 1585 Schedules using this object are first 1586 started. If not present it defaults to 1587 immediate. 1589 ma-calendar-end: The optional date and time at which 1590 Schedules using this object are last 1591 started. If not present it defaults to 1592 indefinite. 1594 ma-calendar-months: The optional set of months (1-12) on 1595 which tasks scheduled using this object 1596 are started. The wildcard * means all 1597 months. If not present, it defaults to 1598 no months. 1600 ma-calendar-days-of-week: The optional set of days of a week 1601 ("Mon", "Tue", "Wed", "Thu", "Fri", 1602 "Sat", "Sun") on which tasks scheduled 1603 using this object are started. The 1604 wildcard * means all days of the week. 1605 If not present, it defaults to no days. 1607 ma-calendar-days-of-month: The optional set of days of a months 1608 (1-31) on which tasks scheduled using 1609 this object are started. The wildcard 1610 * means all days of a months. If not 1611 present, it defaults to no days. 1613 ma-calendar-hours: The optional set of hours (0-23) on 1614 which tasks scheduled using this object 1615 are started. The wildcard * means all 1616 hours of a day. If not present, it 1617 defaults to no hours. 1619 ma-calendar-minutes: The optional set of minutes (0-59) on 1620 which tasks scheduled using this object 1621 are started. The wildcard * means all 1622 minutes of an hour. If not present, it 1623 defaults to no hours. 1625 ma-calendar-seconds: The optional set of seconds (0-59) on 1626 which tasks scheduled using this object 1627 are started. The wildcard * means all 1628 seconds of an hour. If not present, it 1629 defaults to no seconds. 1631 ma-calendar-timezone-offset: The optional timezone offest in hours. 1632 If not present, it defaults to the 1633 system's local timezone. 1635 If a day of the month is specified that does not exist in the month 1636 (e.g., 29th of Feburary) then those values are ignored. 1638 3.10.4. Definition of ma-one-off-obj 1640 object { 1641 datetime ma-one-off-time; 1642 } ma-one-off-obj; 1644 The ma-one-off-obj timing object specifies a fixed point in time. 1645 Schedules using an ma-one-off-obj are started once at the specified 1646 date and time. The ma-one-off-obj consists of the following 1647 elements: 1649 ma-one-off-time: The date and time at which Schedules using 1650 this object are started. 1652 3.10.5. Definition of ma-immediate-obj 1654 object { 1655 // empty 1656 } ma-immediate-obj; 1658 The ma-immediate-obj event object has no further information 1659 elements. Schedules using an ma-immediate-obj are started as soon as 1660 possible. 1662 3.10.6. Definition of ma-startup-obj 1664 object { 1665 // empty 1666 } ma-startup-obj; 1668 The ma-startup-obj event object has no further information elements. 1669 Schedules using an ma-startup-obj are started at MA initiation time. 1671 4. IANA Considerations 1673 This document makes no request of IANA. 1675 Note to RFC Editor: this section may be removed on publication as an 1676 RFC. 1678 5. Security Considerations 1680 This Information Model deals with information about the control and 1681 reporting of the Measurement Agent. There are broadly two security 1682 considerations for such an Information Model. Firstly the 1683 Information Model has to be sufficient to establish secure 1684 communication channels to the Controller and Collector such that 1685 other information can be sent and received securely. Additionally, 1686 any mechanisms that the Network Operator or other device 1687 administrator employs to pre-configure the MA must also be secure to 1688 protect unauthorized parties from modifying pre-configuration 1689 information. These mechanisms are important to ensure that the MA 1690 cannot be hijacked, for example to participate in a DDoS attack. 1692 The second consideration is that no mandated information items should 1693 pose a risk to confidentiality or privacy given such secure 1694 communication channels. For this latter reason items such as the MA 1695 context and MA ID are left optional and can be excluded from some 1696 deployments. This would, for example, allow the MA to remain 1697 anonymous and for information about location or other context that 1698 might be used to identify or track the MA to be omitted or blurred. 1700 The Information Model should support wherever relevant, all the 1701 security and privacy requirements associated with the LMAP Framework. 1703 6. Acknowledgements 1705 The notation was inspired by the notation used in the ALTO protocol 1706 specification. 1708 Philip Eardley, Trevor Burbridge, Marcelo Bagnulo and Juergen 1709 Schoenwaelder work in part on the Leone research project, which 1710 receives funding from the European Union Seventh Framework Programme 1711 [FP7/2007-2013] under grant agreement number 317647. 1713 7. References 1715 7.1. Normative References 1717 [I-D.ietf-lmap-framework] 1718 Eardley, P., Morton, A., Bagnulo, M., Burbridge, T., 1719 Aitken, P., and A. Akhter, "A framework for Large-Scale 1720 Measurement of Broadband Performance (LMAP)", draft-ietf- 1721 lmap-framework-12 (work in progress), March 2015. 1723 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1724 Requirement Levels", BCP 14, RFC 2119, March 1997. 1726 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 1727 Internet: Timestamps", RFC 3339, July 2002. 1729 7.2. Informative References 1731 [I-D.ietf-ippm-metric-registry] 1732 Bagnulo, M., Claise, B., Eardley, P., Morton, A., and A. 1733 Akhter, "Registry for Performance Metrics", draft-ietf- 1734 ippm-metric-registry-02 (work in progress), February 2015. 1736 [I-D.ietf-lmap-yang] 1737 Schoenwaelder, J. and V. Bajpai, "A YANG Data Model for 1738 LMAP Measurement Agents", draft-ietf-lmap-yang-00 (work in 1739 progress), April 2015. 1741 [RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between 1742 Information Models and Data Models", RFC 3444, January 1743 2003. 1745 Appendix A. Open Issues 1747 o Should the execution-mode have a default? If so, which one? 1749 o Is the current handling of lost connectivity to the controller 1750 sufficient? 1752 o There should be status objects for schedules and actions instead 1753 of tasks (since what is being invoked are schedules and actions, 1754 not configured tasks). The status objects should also indicate 1755 whether a schedule is enabled, suppressed, disabled (e.g. due to 1756 loss of controller connectivity), or disabled for any other 1757 reason. 1759 Appendix B. Non-editorial Changes since -05 1761 o A task can now reference multiply registry entries. 1763 o Consistent usage of the term Action and Task. 1765 o Schedules are triggered by Events instead of Timings; Timings are 1766 just one of many possible event sources. 1768 o Actions feed into other Schedules (instead of Actions within other 1769 Schedules). 1771 o Removed the notion of multiple task outputs. 1773 o Support for sequential, parallel, and pipelined execution of 1774 Actions. 1776 Authors' Addresses 1778 Trevor Burbridge 1779 BT 1780 Adastral Park, Martlesham Heath 1781 Ipswich IP5 3RE 1782 United Kingdom 1784 Email: trevor.burbridge@bt.com 1786 Philip Eardley 1787 BT 1788 Adastral Park, Martlesham Heath 1789 Ipswich IP5 3RE 1790 United Kingdom 1792 Email: philip.eardley@bt.com 1793 Marcelo Bagnulo 1794 Universidad Carlos III de Madrid 1795 Av. Universidad 30 1796 Leganes, Madrid 28911 1797 Spain 1799 Email: marcelo@it.uc3m.es 1801 Juergen Schoenwaelder 1802 Jacobs University Bremen 1803 Campus Ring 1 1804 Bremen 28759 1805 Germany 1807 Email: j.schoenwaelder@jacobs-university.de