idnits 2.17.1 draft-ietf-lmap-information-model-05.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 642 has weird spacing: '...ion-obj ma-su...' == Line 1002 has weird spacing: '...ask-obj ma-re...' == Line 1029 has weird spacing: '...row-obj ma-r...' == Line 1167 has weird spacing: '...est-obj ma-...' == Line 1192 has weird spacing: '... string ma-...' == (5 more instances...) -- The document date (April 10, 2015) is 3303 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) -- Looks like a reference, but probably isn't: '1' on line 1217 -- Looks like a reference, but probably isn't: '2' on line 1217 == Unused Reference: 'I-D.ietf-lmap-yang' is defined on line 1722, but no explicit reference was found in the text == 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 (~~), 12 warnings (==), 3 comments (--). 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: October 12, 2015 M. Bagnulo 6 Universidad Carlos III de Madrid 7 J. Schoenwaelder 8 Jacobs University Bremen 9 April 10, 2015 11 Information Model for Large-Scale Measurement Platforms (LMAP) 12 draft-ietf-lmap-information-model-05 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 October 12, 2015. 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 . . . . . . . . . . . . . . . . 9 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 . . . . . . . . . . 14 74 3.4. Logging Information . . . . . . . . . . . . . . . . . . . 15 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 . . . . . . . . . . . . . 17 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 . . . . . . . . . . . . . 21 82 3.6.2. Definition of ma-report-task-obj . . . . . . . . . . 22 83 3.6.3. Definition of ma-report-row-obj . . . . . . . . . . . 23 84 3.7. Common Objects: Schedules . . . . . . . . . . . . . . . . 23 85 3.7.1. Definition of ma-schedule-obj . . . . . . . . . . . . 25 86 3.7.2. Definition of ma-action-obj . . . . . . . . . . . . . 25 87 3.7.3. Definition of ma-action-dest-obj . . . . . . . . . . 26 88 3.8. Common Objects: Channels . . . . . . . . . . . . . . . . 26 89 3.8.1. Definition of ma-channel-obj . . . . . . . . . . . . 27 90 3.9. Common Objects: Task Configurations . . . . . . . . . . . 28 91 3.9.1. Definition of ma-task-obj . . . . . . . . . . . . . . 29 92 3.9.2. Definition of ma-option-obj . . . . . . . . . . . . . 30 93 3.10. Common Objects: Timing Information . . . . . . . . . . . 30 94 3.10.1. Definition of ma-timing-obj . . . . . . . . . . . . 31 95 3.10.2. Definition of ma-periodic-obj . . . . . . . . . . . 32 96 3.10.3. Definition of ma-calendar-obj . . . . . . . . . . . 33 97 3.10.4. Definition of ma-one-off-obj . . . . . . . . . . . . 35 98 3.10.5. Definition of ma-immediate-obj . . . . . . . . . . . 35 99 3.10.6. Definition of ma-startup-obj . . . . . . . . . . . . 35 100 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 101 5. Security Considerations . . . . . . . . . . . . . . . . . . . 36 102 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 36 103 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 36 104 7.1. Normative References . . . . . . . . . . . . . . . . . . 36 105 7.2. Informative References . . . . . . . . . . . . . . . . . 37 106 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 37 108 1. Introduction 110 A large-scale measurement platform is a collection of components that 111 work in a coordinated fashion to perform measurements from a large 112 number of vantage points. The main components of a large-scale 113 measurement platform are the Measurement Agents (hereafter MAs), the 114 Controller(s) and the Collector(s). 116 The MAs are the elements actually performing the measurements. The 117 MAs are controlled by exactly one Controller at a time and the 118 Collectors gather the results generated by the MAs. In a nutshell, 119 the normal operation of a large-scale measurement platform starts 120 with the Controller instructing a set of one or more MAs to perform a 121 set of one or more Measurement Tasks at a certain point in time. The 122 MAs execute the instructions from a Controller, and once they have 123 done so, they report the results of the measurements to one or more 124 Collectors. The overall framework for a Large Measurement platform 125 as used in this document is described in detail in 126 [I-D.ietf-lmap-framework]. 128 A large-scale measurement platform involves basically three types of 129 protocols, namely, a Control protocol (or protocols) between a 130 Controller and the MAs, a Report protocol (or protocols) between the 131 MAs and the Collector(s) and several measurement protocols between 132 the MAs and Measurement Peers (MPs), used to actually perform the 133 measurements. In addition some information is required to be 134 configured on the MA prior to any communication with a Controller. 136 This document defines the information model for both Control and the 137 Report protocols along with pre-configuration information that is 138 required on the MA before communicating with the Controller, broadly 139 named as the LMAP Information Model. The measurement protocols are 140 out of the scope of this document. 142 As defined in [RFC3444], the LMAP Information Model (henceforth also 143 referred to as LMAP IM) defines the concepts involved in a large- 144 scale measurement platform at a high level of abstraction, 145 independent of any specific implementation or actual protocol used to 146 exchange the information. It is expected that the proposed 147 information model can be used with different protocols in different 148 measurement platform architectures and across different types of MA 149 devices (e.g., home gateway, smartphone, PC, router). 151 The definition of an Information Model serves a number of purposes: 153 1. To guide the standardisation of one or more Control and Report 154 protocols and data models 156 2. To enable high-level inter-operability between different Control 157 and Report protocols by facilitating translation between their 158 respective data models such that a Controller could instruct sub- 159 populations of MAs using different protocols 161 3. To form agreement of what information needs to be held by an MA 162 and passed over the Control and Report interfaces and support the 163 functionality described in the LMAP framework 165 4. Enable existing protocols and data models to be assessed for 166 their suitability as part of a large-scale measurement system 168 2. Notation 170 This document use an object-oriented programming-like notation to 171 define the parameters (names/values) of the objects of the 172 information model. An optional field is enclosed by [ ], and an 173 array is indicated by two numbers in angle brackets, , where m 174 indicates the minimal number of values, and n is the maximum. The 175 symbol * for n means no upper bound. 177 3. LMAP Information Model 179 The information described herein relates to the information stored, 180 received or transmitted by a Measurement Agent as described within 181 the LMAP framework [I-D.ietf-lmap-framework]. As such, some subsets 182 of this information model are applicable to the measurement 183 Controller, Collector and any device management system that pre- 184 configures the Measurement Agent. The information described in these 185 models will be transmitted by protocols using interfaces between the 186 Measurement Agent and such systems according to a Data Model. 188 For clarity the information model is divided into six sections: 190 1. Pre-Configuration Information. Information pre-configured on the 191 Measurement Agent prior to any communication with other 192 components of the LMAP architecture (i.e., the Controller, 193 Collector and Measurement Peers), specifically detailing how to 194 communicate with a Controller and whether the device is enabled 195 to participate as an MA. 197 2. Configuration Information. Update of the pre-configuration 198 information during the registration of the MA or subsequent 199 communication with the Controller, along with the configuration 200 of further parameters about the MA (rather than the Tasks it 201 should perform) that were not mandatory for the initial 202 communication between the MA and a Controller. 204 3. Instruction Information. Information that is received by the MA 205 from the Controller pertaining to the Tasks that should be 206 executed. This includes the task execution Schedules (other than 207 the Controller communication Schedule supplied as 208 (pre)configuration information) and related information such as 209 the Task Configuration, communication Channels to Collectors and 210 schedule Timing information. It also includes Task Suppression 211 information that is used to over-ride normal Task execution. 213 4. Logging Information. Information transmitted from the MA to the 214 Controller detailing the results of any configuration operations 215 along with error and status information from the operation of the 216 MA. 218 5. Capability and Status Information. Information on the general 219 status and capabilities of the MA. For example, the set of 220 measurements that are supported on the device. 222 6. Reporting Information. Information transmitted from the MA to 223 one or more Collectors including measurement results and the 224 context in which they were conducted. 226 In addition the MA may hold further information not described herein, 227 and which may be optionally transferred to or from other systems 228 including the Controller and Collector. One example of information 229 in this category is subscriber or line information that may be 230 extracted by a task and reported by the MA in the reporting 231 communication to a Collector. 233 It should also be noted that the MA may be in communication with 234 other management systems which may be responsible for configuring and 235 retrieving information from the MA device. Such systems, where 236 available, can perform an important role in transferring the pre- 237 configuration information to the MA or enabling/disabling the 238 measurement functionality of the MA. 240 The Information Model is divided into sub-sections for a number of 241 reasons. Firstly the grouping of information facilitates reader 242 understanding. Secondly, the particular groupings chosen are 243 expected to map to different protocols or different transmissions 244 within those protocols. 246 The granularity of data transmitted in each operation of the Control 247 and Report Protocols is not dictated by the Information Model. For 248 example, the Instruction object may be delivered in a single 249 operation. Alternatively, Schedules and Task Configurations may be 250 separated or even each Schedule/Task Configuration may be delivered 251 individually. Similarly the Information Model does not dictate 252 whether data is read, write, or read/write. For example, some 253 Control Protocols may have the ability to read back Configuration and 254 Instruction information which have been previously set on the MA. 255 Lastly, while some protocols may simply overwrite information (for 256 example refreshing the entire Instruction Information), other 257 protocols may have the ability to update or delete selected items of 258 information. 260 The information in these six sections is captured by a number of 261 common information objects. These objects are also described later 262 in this document and comprise of: 264 1. Schedules. A set of Schedules tell the MA to do something. 265 Without a Schedule no Task (from a measurement to reporting or 266 communicating with the Controller) is ever executed. Schedules 267 are used within the Instruction to specify what tasks should be 268 performed, when, and how to direct their results. A Schedule is 269 also used within the pre-Configuration and Configuration 270 information in order to execute the Task or Tasks required to 271 communicate with the Controller. 273 2. Channels. A set of Channel objects are used to communicate with 274 a number of endpoints (i.e., the Controller and Collectors). 275 Each Channel object contains the information required for the 276 communication with a single endpoint such as the target location 277 and security details. 279 3. Task Configurations. A set of Task Configurations is used to 280 configure the Tasks that are run by the MA. This includes the 281 registry entry for the Task and any configuration parameters. 282 Task Configurations are referenced from a Schedule in order to 283 specify what Tasks the MA should execute. 285 4. Timings. A set of Timing objects that can be referenced from the 286 Schedules. Each Schedule always references exactly one Timing 287 object. A Timing object specifies either a singleton or series 288 of time events. They are used to indicate when Tasks should be 289 executed. 291 The following diagram illustrates the structure in which these common 292 information objects are referenced. The references are achieved by 293 each object (Task Configuration, Timing) being given a short text 294 name that is used by other objects. The objects shown in parenthesis 295 are part of the internal object structure of a Schedule. Channels 296 are not shown in the diagram since they are only used as an option by 297 selected Task Configurations but are similarly referenced using a 298 short text name. 300 Schedule 301 |----------> Timing 302 |----------> (Scheduled Tasks) 303 |----------> Task Configuration 304 |----------> Destination Tasks 306 It should be clear that the top-level behavior of an MA is simply to 307 execute Schedules. Every action referenced by a Schedule is defined 308 as a Task. As such, these actions are configured through Task 309 Configurations and executed according to the Timing referenced by the 310 Schedule in which they appear. Tasks can implement a variety of 311 different types of actions. While in terms of the Information Model, 312 all Tasks have the same structure, it can help conceptually to think 313 of different Task categories: 315 1. Measurement Tasks measure some aspect of network performance or 316 traffic. They may also capture contextual information from the 317 MA device or network interfaces such as the device type or 318 interface speed. 320 2. Data Transfer Tasks 322 A. Reporting Tasks report the results of Measurement Tasks to 323 Collectors 325 B. Control Task(s) implement the Control Protocol and 326 communicate with the Controller. Depending on the Control 327 Protocol there may be a number of specialist tasks such as: 328 Configuration Task; Instruction Task; Suppression Task; 329 Capabilities Task; Logging Task etc. 331 3. Data Analysis Tasks can exist to analyse data from other 332 Measurement Tasks locally on the MA 334 4. Data Management Tasks may exist to clean-up, filter or compress 335 data on the MA such as Measurement Task results 337 3.1. Pre-Configuration Information 339 This information is the minimal information that needs to be pre- 340 configured to the MA in order for it to successfully communicate with 341 a Controller during the registration process. Some of the Pre- 342 Configuration Information elements are repeated in the Configuration 343 Information in order to allow an LMAP Controller to update these 344 items. The pre-configuration information also contains some elements 345 that are not under the control of the LMAP framework (such as the 346 device identifier and device security credentials). 348 This Pre-Configuration Information needs to include a URL of the 349 initial Controller from where configuration information can be 350 communicated along with the security information required for the 351 communication including the certificate of the Controller (or the 352 certificate of the Certification Authority which was used to issue 353 the certificate for the Controller). All this is expressed as a 354 Channel. While multiple Channels may be provided in the Pre- 355 Configuration Information they must all be associated with a single 356 Controller (e.g., over different interfaces or network protocols). 358 Where the MA pulls information from the Controller, the Pre- 359 Configuration Information also needs to contain the timing of the 360 communication with the Controller as well as the nature of the 361 communication itself (such as the protocol and data to be 362 transferred). The timing is given as a Schedule that executes the 363 Task(s) responsible for communication with the Controller. It is 364 this Task (or Tasks) that implement the Control protocol between the 365 MA and the Controller and utilises the Channel information. The 366 Task(s) may take additional parameters in which case a Task 367 Configuration can also be included. 369 Even where information is pushed to the MA from the Controller 370 (rather than pulled by the MA), a Schedule still needs to be 371 supplied. In this case the Schedule will simply execute a Controller 372 listener task when the MA is started. A Channel is still required 373 for the MA to establish secure communication with the Controller. 375 It can be seen that these Channels, Schedules and Task Configurations 376 for the initial MA-Controller communication are no different in terms 377 of the Information Model to any other Channel, Schedule or Task 378 Configuration that might execute a Measurement Task or report the 379 measurement results (as described later). 381 The MA may be pre-configured with an MA ID, or may use a Device ID in 382 the first Controller contact before it is assigned an MA ID. The 383 Device ID may be a MAC address or some other device identifier 384 expressed as a URI. If the MA ID is not provided at this stage then 385 it must be provided by the Controller during Configuration. 387 3.1.1. Definition of ma-preconfig-obj 389 object { 390 [uuid ma-agent-id;] 391 ma-task-obj ma-control-tasks<1..*>; 392 ma-channel-obj ma-control-channels<1..*>; 393 ma-schedule-obj ma-control-schedules<1..*>; 394 [uri ma-device-id;] 395 credentials ma-credentials; 396 } ma-preconfig-obj; 398 The ma-preconfig-obj is essentially a subset of the ma-config-obj 399 described below. The ma-preconfig-obj consists of the following 400 elements: 402 ma-agent-id: An optional uuid uniquely identifying the 403 measurement agent. 405 ma-control-tasks: A collection of tasks objects. 407 ma-control-channels: A collection of channel objects. 409 ma-control-schedules: A collection of scheduling objects. 411 ma-device-id: An optional identifier for the device. 413 ma-credentials: The security credentials used by the 414 measurement agent. 416 3.2. Configuration Information 418 During registration or at any later point at which the MA contacts 419 the Controller (or vice-versa), the choice of Controller, details for 420 the timing of communication with the Controller or parameters for the 421 communication Task(s) can be changed (as captured by the Channels, 422 Schedules and Task Configurations objects). For example the pre- 423 configured Controller (specified as a Channel or Channels) may be 424 over-ridden with a specific Controller that is more appropriate to 425 the MA device type, location or characteristics of the network (e.g., 426 access technology type or broadband product). The initial 427 communication Schedule may be over-ridden with one more relevant to 428 routine communications between the MA and the Controller. 430 While some Control protocols may only use a single Schedule, other 431 protocols may use several Schedules (and related data transfer Tasks) 432 to update the Configuration Information, transfer the Instruction 433 Information, transfer Capability and Status Information and send 434 other information to the Controller such as log or error 435 notifications. Multiple Channels may be used to communicate with the 436 same Controller over multiple interfaces (e.g., to send logging 437 information over a different network). 439 In addition the MA will be given further items of information that 440 relate specifically to the MA rather than the measurements it is to 441 conduct or how to report results. The assignment of an ID to the MA 442 is mandatory. If the MA Agent ID was not optionally provided during 443 the pre-configuration then one must be provided by the Controller 444 during Configuration. Optionally a Group ID may also be given which 445 identifies a group of interest to which that MA belongs. For example 446 the group could represent an ISP, broadband product, technology, 447 market classification, geographic region, or a combination of 448 multiple such characteristics. Where the Measurement Group ID is set 449 an additional flag (the Report MA ID flag) is required to control 450 whether the Measurement Agent ID is also to be reported. The 451 reporting of a Group ID without the MA ID allows the MA to remain 452 anonymous, which may be particularly useful to prevent tracking of 453 mobile MA devices. 455 Optionally an MA can also be configured to stop executing any 456 Instruction Schedule if the Controller is unreachable. This can be 457 used as a fail-safe to stop Measurement and other Tasks being 458 conducted when there is doubt that the Instruction Information is 459 still valid. This is simply represented as a time window in 460 milliseconds since the last communication with the Controller after 461 which Instruction Schedules are to be suspended. The appropriate 462 value of the time window will depend on the specified communication 463 Schedule with the Controller and the duration for which the system is 464 willing to tolerate continued operation with potentially stale 465 Instruction Information. 467 While Pre-Configuration Information is persistent upon device reset 468 or power cycle, the persistency of the Configuration Information may 469 be device dependent. Some devices may revert back to their pre- 470 configuration state upon reboot or factory reset, while other devices 471 may store all Configuration and Instruction information in persistent 472 storage. A Controller can check whether an MA has the latest 473 Configuration and Instruction information by examining the Capability 474 and Status information for the MA. 476 It should be noted that control schedules and tasks cannot be 477 suppressed as evidenced by the lack of suppression information in the 478 Configuration. The control schedule must only reference tasks listed 479 as control tasks (i.e., within the Configuration information). Any 480 suppress-by-default flag against control tasks will be ignored. 482 3.2.1. Definition of ma-config-obj 484 object { 485 uuid ma-agent-id; 486 ma-task-obj ma-control-tasks<1..*>; 487 ma-channel-obj ma-control-channels<1..*>; 488 ma-schedule-obj ma-control-schedules<1..*>; 489 [uri ma-device-id;] 490 credentials ma-credentials; 491 [string ma-group-id;] 492 [boolean ma-report-agent-id;] 493 [int ma-controller-lost-timeout;] 494 } ma-config-obj; 496 The ma-config-obj consists of the following elements: 498 ma-agent-id: A uuid uniquely identifying the measurement 499 agent. 501 ma-control-tasks: A collection of task objects. 503 ma-control-channels: A collection of channel objects. 505 ma-control-schedules: A collection of scheduling objects. 507 ma-device-id: An optional identifier for the device. 509 ma-credentials: The security credentials used by the 510 measurement agent. 512 ma-group-id: An optional identifier of the group of 513 measurement agents this measurement agent 514 belongs to. 516 ma-report-agent-id: An optional flag indicating whether the 517 identifier (ma-agent-id) should be included 518 in reports. 520 ma-controller-lost-timeout: A timer is started after each successful 521 contact with a controller. When the timer 522 reaches the controller-lost-timeout, all 523 schedules will be disabled. 525 3.3. Instruction Information 527 The Instruction information model has four sub-elements: 529 1. Instruction Task Configurations 531 2. Report Channels 533 3. Instruction Schedules 535 4. Suppression 537 The Instruction supports the execution of all Tasks on the MA except 538 those that deal with communication with the Controller (specified in 539 (pre-)configuration information). The Tasks are configured in 540 Instruction Task Configurations and included by reference in 541 Instruction Schedules that specify when to execute them. The results 542 can be communicated to other Tasks or a Task may implement a 543 Reporting Protocol and communicate results over Report Channels. 544 Suppression is used to temporarily stop the execution of new Tasks as 545 specified by the Instruction Schedules (and optionally to stop 546 ongoing Tasks). 548 A Task Configuration is used to configure the mandatory and optional 549 parameters of a Task. It also serves to instruct the MA about the 550 Task including the ability to resolve the Task to an executable and 551 specifying the schema for the Task parameters. 553 A Report Channel defines how to communicate with a single remote 554 system specified by a URL. A Report Channel is used to send results 555 to single Collector but is no different in terms of the Information 556 Model to the Control Channel used to transfer information between the 557 MA and the Controller. Several Report Channels can be defined to 558 enable results to be split or duplicated across different 559 destinations. A single Channel can be used by multiple (reporting) 560 Task Configurations to transfer data to the same Collector. A single 561 Reporting Task Configuration can also be included in multiple 562 Schedules. E.g., a single Collector may receive data at three 563 different cycle rates, one Schedule reporting hourly, another 564 reporting daily and a third specifying that results should be sent 565 immediately for on-demand measurement tasks. Alternatively multiple 566 Report Channels can be used to send Measurement Task results to 567 different Collectors. The details of the Channel element is 568 described later as it is common to several objects. 570 Instruction Schedules specify which Tasks to execute according to a 571 given Timing (that can execute a single or repeated series of Tasks). 573 The Schedule also specifies how to link Tasks output data to other 574 scheduled Tasks, i.e., sending selected outputs to other Tasks. 576 Measurement Suppression information is used to over-ride the 577 Instruction Schedule and temporarily stop measurements or other Tasks 578 from running on the MA for a defined or indefinite period. While 579 conceptually measurements can be stopped by simply removing them from 580 the Measurement Schedule, splitting out separate information on 581 Measurement Suppression allows this information to be updated on the 582 MA on a different timing cycle or protocol implementation to the 583 Measurement Schedule. It is also considered that it will be easier 584 for a human operator to implement a temporary explicit suppression 585 rather than having to move to a reduced Schedule and then roll-back 586 at a later time. 588 The explicit Suppression instruction message is able to simply 589 enable/disable all Instruction Tasks (that are enabled for default 590 suppression) as well as having fine control on which Tasks are 591 suppressed. Suppression of both specified Task Configurations and 592 Measurement Schedules is supported. Support for disabling specific 593 Task Configurations allows malfunctioning or mis-configured Tasks or 594 Task Configurations that have an impact on a particular part of the 595 network infrastructure (e.g., a particular Measurement Peer) to be 596 targeted. Support for disabling specific Schedules allows for 597 particularly heavy cycles or sets of less essential Measurement Tasks 598 to be suppressed quickly and effectively. Note that Suppression has 599 no effect on either Controller Tasks or Controller Schedules. 601 When no tasks or schedules are explicitly listed, all Instruction 602 tasks will be suppressed (or not) as indicated by the suppress-by- 603 default flag in the Task Configuration. If tasks or schedules are 604 listed explicitly then only these listed tasks or schedules will be 605 suppressed regardless of the suppress-by-default flag. If both 606 individual tasks and individual schedules are listed then only the 607 listed schedules, plus the listed tasks where present in other 608 schedules, will be suppressed regardless of the suppress-by-default 609 flag. 611 Suppression stops new Tasks from executing. In addition, the 612 Suppression information also supports an additional Boolean that is 613 used to select whether on-going tasks are also to be terminated. 615 Unsuppression is achieved through either overwriting the Measurement 616 Suppression information (e.g., changing 'enabled' to False) or 617 through the use of an End time such that the Measurement Suppression 618 will no longer be in effect beyond this time. The datetime format 619 used for all elements in the information model (e.g., the suppression 620 start and end dates) MUST conform to RFC 3339 [RFC3339]. 622 The goal when defining these four different elements is to allow each 623 part of the information model to change without affecting the other 624 three elements. For example it is envisaged that the Report Channels 625 and the set of Task Configurations will be relatively static. The 626 Instruction Schedule, on the other hand, is likely to be more 627 dynamic, as the measurement panel and test frequency are changed for 628 various business goals. Another example is that measurements can be 629 suppressed with a Suppression command without removing the existing 630 Instruction Schedules that would continue to apply after the 631 Suppression expires or is removed. In terms of the Controller-MA 632 communication this can reduce the data overhead. It also encourages 633 the re-use of the same standard Task Configurations and Reporting 634 Channels to help ensure consistency and reduce errors. 636 3.3.1. Definition of ma-instruction-obj 638 object { 639 ma-task-obj ma-instruction-tasks<0..*>; 640 ma-channel-obj ma-report-channels<0..*>; 641 ma-schedule-obj ma-instruction-schedules<0..*>; 642 ma-suppression-obj ma-suppression; 643 } ma-instruction-obj; 645 An ma-instruction-obj consists of the following elements: 647 ma-task-obj: A possibly empty collection of task objects. 649 ma-channel-obj: A possibly empty collection of channel objects. 651 ma-schedule-obj: A possibly empty collection of schedule objects. 653 ma-suppression-obj: A suppression object. 655 3.3.2. Definition of ma-suppression-obj 657 object { 658 boolean ma-suppression-enabled; 659 [boolean ma-suppression-stop-running;] 660 [datetime ma-suppression-start;] 661 [datetime ma-suppression-end;] 662 [string ma-suppression-task-names<0..*>;] 663 [string ma-suppression-schedule-names<0..*>;] 664 } ma-suppression-obj; 666 The ma-suppression-obj consists of the following elements: 668 ma-suppression-enabled: A boolean indicating whether 669 suppression is enabled or not. The 670 default value is false. 672 ma-suppression-stop-running: An optional boolean indicating 673 whether suppression will stop any 674 running tasks. The default value for 675 this boolean is false. 677 ma-suppression-start: The optional date and time when 678 suppression starts. The default 679 value is 'immediate'. 681 ma-suppression-end: The optional date and time when 682 suppression ends. The default value 683 is 'indefinite'. 685 ma-suppression-task-names: An optional and possibly empty 686 collection of task names. If not 687 present, this defaults to all tasks. 689 ma-suppression-schedule-names: An optional and possibly empty 690 collection of schedule names. If not 691 present, this defaults to all 692 schedules. 694 3.4. Logging Information 696 The MA may report on the success or failure of Configuration or 697 Instruction communications from the Controller. In addition further 698 operational logs may be produced during the operation of the MA and 699 updates to capabilities may also be reported. Reporting this 700 information is achieved in exactly the same manner as scheduling any 701 other Task. We make no distinction between a Measurement Task 702 conducting an active or passive network measurement and one which 703 solely retrieves static or dynamic information from the MA such as 704 capabilities or logging information. One or more logging tasks can 705 be programmed or configured to capture subsets of the Logging 706 Information. These logging tasks are then executed by Schedules 707 which also specify that the resultant data is to be transferred over 708 the Controller Channels. 710 The type of Logging Information will fall into three different 711 categories: 713 1. Success/failure/warning messages in response to information 714 updates from the Controller. Failure messages could be produced 715 due to some inability to receive or parse the Controller 716 communication, or if the MA is not able to act as instructed. 717 For example: 719 * "Measurement Schedules updated OK" 721 * "Unable to parse JSON" 723 * "Missing mandatory element: Measurement Timing" 725 * "'Start' does not conform to schema - expected datetime" 727 * "Date specified is in the past" 729 * "'Hour' must be in the range 1..24" 731 * "Schedule A refers to non-existent Measurement Task 732 Configuration" 734 * "Measurement Task Configuration X registry entry Y not found" 736 * "Updated Measurement Task Configurations do not include M used 737 by Measurement Schedule N" 739 2. Operational updates from the MA. For example: 741 * "Out of memory: cannot record result" 743 * "Collector 'collector.example.com' not responding" 745 * "Unexpected restart" 747 * "Suppression timeout" 749 * "Failed to execute Measurement Task Configuration H" 751 3. Status updates from the MA. For example: 753 * "Device interface added: eth3" 755 * "Supported measurements updated" 757 * "New IP address on eth0: xxx.xxx.xxx.xxx" 759 This Information Model document does not detail the precise format of 760 logging information since it is to a large extent protocol and MA 761 specific. However, some common information can be identified. 763 3.4.1. Definition of ma-log-obj 765 object { 766 uuid ma-log-agent-id; 767 datetime ma-log-event-time; 768 code ma-log-code; 769 string ma-log-description; 770 } ma-log-obj; 772 The ma-log-obj models the generic aspects of a logging object and 773 consists of the following elements: 775 ma-log-agent-id: A uuid uniquely identifying the measurement 776 agent. 778 ma-log-event-time: The date and time of the event reported in 779 the logging object. 781 ma-log-code: A machine readable code describing the 782 event. 784 ma-log-description: A human readable description of the event. 786 3.5. Capability and Status Information 788 The MA will hold Capability Information that can be retrieved by a 789 Controller. Capabilities include the device interface details 790 available to Measurement Tasks as well as the set of Measurement 791 Tasks/Roles (specified by a registry entry) that are actually 792 installed or available on the MA. Status information includes the 793 times that operations were last performed such as contacting the 794 Controller or producing Reports. 796 3.5.1. Definition of ma-status-obj 798 object { 799 uuid ma-agent-id; 800 uri ma-device-id; 801 string ma-hardware; 802 string ma-firmware; 803 string ma-version; 804 ma-interface-obj ma-interfaces<0..*>; 805 datetime ma-last-started; 806 [ma-task-status-obj ma-task-status<0..*>;] 807 } ma-status-obj; 809 The ma-status-obj provides status information about the measurement 810 agent and consists of the following elements: 812 ma-agent-id: A uuid uniquely identifying the measurement 813 agent. 815 ma-device-id: A URI identifying the device. 817 ma-hardware: A description of the hardware of the device 818 the measurement agent is running on. 820 ma-firmware: A description of the firmware of the device 821 the measurement agent is running on. 823 ma-version: The version of the measurement agent. 825 ma-interfaces: A list of network interfaces available on 826 the device. 828 ma-last-started: The date and time the measurement agent 829 last started. 831 ma-task-status: An optional list of status objects for each 832 supported task. 834 3.5.2. Definition of ma-task-status-obj 836 object { 837 string ma-task-name; 838 [uri ma-task-registry-entry;] 839 [string ma-task-role<0..*>;] 840 datetime ma-task-last-invocation; 841 datetime ma-task-last-completion; 842 int ma-task-last-status; 843 string ma-task-last-message; 844 datetime ma-task-last-failed-completion; 845 int ma-task-last-failed-status; 846 string ma-task-last-failed-message; 847 } ma-task-status-obj; 849 The ma-task-status-obj provides status information about a task and 850 consists of the following elements: 852 ma-task-name: A name uniquely identifying a task. 854 ma-task-registry-entry: An optional URI identifying the 855 nature of the task. 857 ma-task-role: An optional and possibly empty list 858 of roles of a task. 860 ma-task-last-completion: The date and time of the last 861 completion of this task. 863 ma-task-last-status: The status code returned by the last 864 execution of this task. 866 ma-task-last-message: The status message produced by the 867 last execution of this task. 869 ma-task-last-failed-completion: The date and time of the last failed 870 completion of this task. 872 ma-task-last-failed-status: The status code returned by the last 873 failed execution of this task. 875 ma-task-last-failed-message: The status message produced by the 876 last failed execution of this task. 878 3.5.3. Definition of ma-interface-obj 880 object { 881 string ma-interface-name; 882 string ma-interface-type; 883 [int ma-interface-speed;] 884 [string ma-interface-link-layer-address;] 885 [ip-address ma-interface-ip-addresses<0..*>]; 886 [ip-address ma-interface-gateways<0..*>;] 887 [ip-address ma-interface-dns-servers<0..*>;] 888 } ma-interface-obj; 890 The ma-interface-obj provides status information about network 891 interfaces and consists of the following elements: 893 ma-interface-name: A name uniquely identifying a 894 network interface. 896 ma-interface-type: The type of the network interface. 898 ma-interface-speed: An optional indication of the speed 899 of the interface (measured in bits- 900 per-second). 902 ma-interface-link-layer-address: An optional link-layer address of 903 the interface. 905 ma-interface-ip-addresses: An optional list of IP addresses 906 assigned to the interface. 908 ma-interface-gateways: An optional list of gateways 909 assigned to the interface. 911 ma-interface-dns-servers: An optional list of DNS servers 912 assigned to the interface. 914 3.6. Reporting Information 916 At a point in time specified by a Schedule, the MA will execute a 917 task or tasks that communicate a set of measurement results to the 918 Collector. These Reporting Tasks will be configured to transmit task 919 results over a specified Report Channel to a Collector. 921 It should be noted that the output from Tasks does not need to be 922 sent to communication Channels. It can alternatively, or 923 additionally, be sent to other Tasks on the MA. This facilitates 924 using a first Measurement Task to control the operation of a later 925 Measurement Task (such as first probing available line speed and then 926 adjusting the operation of a video testing measurement) and also to 927 allow local processing of data to output alarms (e.g., when 928 performance drops from earlier levels). Of course, subsequent Tasks 929 also include Tasks that implement the reporting protocol(s) and 930 transfer data to one or more Collector(s). 932 The Report generated by a Reporting Task is structured hierarchically 933 to avoid repetition of report header and Measurement Task 934 Configuration information. The report starts with the timestamp of 935 the report generation on the MA and details about the MA including 936 the optional Measurement Agent ID and Group ID (controlled by the 937 Configuration Information). 939 Much of the report Information is optional and will depend on the 940 implementation of the Reporting Task and any parameters defined in 941 the Task Configuration for the Reporting Task. For example some 942 Reporting Tasks may choose not to include the Measurement Task 943 Configuration or scheduled task parameters, while others may do so 944 dependent on the Controller setting a configurable parameter in the 945 Task Configuration. 947 It is possible for a Reporting Task to send just the Report header 948 (datetime and optional agent ID and/or Group ID) if no measurement 949 data is available. Whether to send such empty reports again is 950 dependent on the implementation of the Reporting Task and potential 951 Task Configuration parameter. 953 The handling of measurement data on the MA before generating a Report 954 and transfer from the MA to the Collector is dependent on the 955 implementation of the device, MA and/or scheduled Tasks and not 956 defined by the LMAP standards. Such decisions may include limits to 957 the measurement data storage and what to do when such available 958 storage becomes depleted. 960 No context information, such as line speed or broadband product are 961 included within the report header information as this data is 962 reported by individual tasks at the time they execute. Either a 963 Measurement Task can report contextual parameters that are relevant 964 to that particular measurement, or specific tasks can be used to 965 gather a set of contextual and environmental data. at certain times 966 independent of the reporting schedule. 968 After the report header information the results are reported grouped 969 according to different Measurement Task Configurations. Each Task 970 section optionally starts with replicating the Measurement Task 971 Configuration information before the result headers (titles for data 972 columns) and the result data rows. The Options reported are those 973 used for the scheduled execution of the Measurement Task and 974 therefore include the Options specified in the Task Configuration as 975 well as additional Options specified in the Scheduled Task. The 976 Scheduled Task Options are appended to the Task Configuration Options 977 in exactly the same order as they were provided to the Task during 978 execution. 980 The result row data includes a time for the start of the measurement 981 and optionally an end time where the duration also needs to be 982 considered in the data analysis. 984 Some Measurement Tasks may optionally include an indication of the 985 cross-traffic although the definition of cross-traffic is left up to 986 each individual Measurement Task. Some Measurement Tasks may also 987 output other environmental measures in addition to cross-traffic such 988 as CPU utlilisation or interface speed. 990 Where the Configuration and Instruction information represent 991 information transmitted via the Control Protocol, the Report 992 represents the information that is transmitted via the Report 993 Protocol. It is constructed at the time of sending a report and 994 represents the inherent structure of the information that is sent to 995 the Collector. 997 3.6.1. Definition of ma-report-obj 998 object { 999 datetime ma-report-date; 1000 [uuid ma-report-agent-id;] 1001 [string ma-report-group-id;] 1002 [ma-report-task-obj ma-report-tasks<0..*>]; 1003 } ma-report-obj; 1005 The ma-report-obj provides the meta-data of a single report and 1006 consists of the following elements: 1008 ma-report-date: The date and time when the report was sent 1009 to a collector. 1011 ma-report-agent-id: An optional uuid uniquely identifying the 1012 measurement agent. 1014 ma-report-group-id: An optional identifier of the group of 1015 measurement agents this measurement agent 1016 belongs to. 1018 ma-report-tasks: An optional and possibly empty list of 1019 tasks result objects. 1021 3.6.2. Definition of ma-report-task-obj 1023 object { 1024 string ma-report-task-name; 1025 [uri ma-report-task-registry-entry;] 1026 [ma-option-obj ma-report-scheduled-task-options<0..*>]; 1027 [string ma-report-task-cycle-id;] 1028 string ma-report-task-column-labels<0..*>; 1029 ma-report-row-obj ma-report-task-rows<0..*>; 1030 } ma-report-task-obj; 1032 The ma-report-task-obj provides the meta-data of a result report of a 1033 single task. It consists of the following elements: 1035 ma-report-task-name: A name uniquely identifying the task 1036 that produced the results being 1037 reported. 1039 ma-report-task-registry-entry: An optional URI identifying the type 1040 of task. 1042 ma-report-task-scheduled-task-options: An optional list of task 1043 options provided by the scheduling 1044 object. 1046 ma-report-task-cycle-id: An optional measurement cycle 1047 identifier. 1049 ma-report-task-column-labels: A possibly empty list of column 1050 labels. 1052 ma-report-task-rows: A possibly empty list of result rows. 1054 3.6.3. Definition of ma-report-row-obj 1056 object { 1057 datetime ma-report-result-start-time; 1058 [datetime ma-report-result-end-time;] 1059 string ma-report-result-conflicts<0..*>; 1060 data ma-report-result-values<0..*>; 1061 } ma-report-row-obj; 1063 The ma-report-row-obj represents a result row and consists of the 1064 following elements: 1066 ma-report-result-start-time: The date and time of the start of the 1067 measurement task that produced the 1068 reported result values. 1070 ma-report-result-end-time: An optional date and time indicating 1071 when the measurement task that produced 1072 the reported result values finished. 1074 ma-report-result-conflicts: A possibly empty set of names of task 1075 that might have impacted the 1076 measurement being reported. 1078 ma-report-result-values: A possibly empty set of result values. 1080 3.7. Common Objects: Schedules 1082 A Schedule specifies the execution of a single or repeated series of 1083 Tasks. Each Schedule contains basically two elements: a list of 1084 Tasks to be executed and a timing object for the Schedule. The 1085 Schedule states what Tasks to run (with what configuration) and when 1086 to run the Tasks. 1088 Multiple Tasks in the list of a single Measurement Schedule will be 1089 executed in order with minimal gaps. Tasks in different Schedules 1090 execute in parallel with such conflicts being reported in the 1091 Reporting Information. If two or more Schedules have the same start 1092 time, then the two will execute in parallel. There is no mechanism 1093 to prioritise one schedule over another or to mutex scheduled tasks. 1095 As well as specifying which Tasks to execute, the Schedule also 1096 specifies how to link the data outputs from each scheduled task to 1097 other scheduled tasks. Specifying this within the Schedule allows 1098 the highest level of flexibility since it is even possible to send 1099 the output from different executions of the same Task Configuration 1100 to different destinations. Since a single Task may have multiple 1101 outputs, the Schedule can independently specify which outputs go to 1102 which destinations. For example, a Measurement Task might report 1103 routine results to a data Reporting Task that communicates hourly via 1104 the Broadband PPP interface, but also outputs emergency conditions 1105 via an alarm Reporting Task communicating immediately over a GPRS 1106 channel. Note that task-to-task data transfer is always specified in 1107 association with the scheduled execution of the sending task - there 1108 is no need for a corresponding input specification for the receiving 1109 task. While it is likely that an MA implementation will use a queue 1110 mechanism between the scheduled tasks, this Information Model does 1111 not mandate or define a queue, or any potential associated parameters 1112 such as storage size and retention policies. 1114 When specifying the task to execute within the Schedule, it is 1115 possible to add to the task configuration option parameters. This 1116 allows the Task Configuration to determine the common characteristics 1117 of a Task, while selected parameters (e.g., the test target URL) are 1118 defined within the schedule. A single Tasks Configuration can even 1119 be used multiple times in the same schedule with different additional 1120 parameters. This allows for efficiency in creating and transferring 1121 the Instruction. Note that the semantics of what happens if an 1122 option is defined multiple times (either in the Task Configuration, 1123 Schedule or in both) is not standardised and will depend upon the 1124 Task. For example, some tasks may legitimately take multiple values 1125 for a single parameter. 1127 Where Options are specified in both the Schedule and the Task 1128 Configuration, the Schedule Options are appended to those specified 1129 in the Task Configuration. 1131 Example: A Schedule references a single Measurement Task 1132 Configuration for the UDP latency. It specifies that results are 1133 to be sent to a scheduled Reporting Task. This Reporting Task is 1134 executed by a separate Schedule that specifies that it should run 1135 hourly at 5 minutes past the hour. When run this Reporting Task 1136 takes the data generated by the UDP latency Task as well as any 1137 other data to be included in the hourly report and transfers it to 1138 the Collector over the Report Channel specified within its own 1139 Schedule. 1141 3.7.1. Definition of ma-schedule-obj 1143 object { 1144 string ma-schedule-name; 1145 ma-action-obj ma-schedule-actions<0..*>; 1146 ma-timing-obj ma-schedule-timing; 1147 } ma-schedule-obj; 1149 The ma-schedule-obj is the main scheduling object. It consists of 1150 the following elements: 1152 ma-schedule-name: A name uniquely identifying a scheduling 1153 object. 1155 ma-schedule-actions: A possibly empty list of actions to invoke 1156 when the schedule fires. 1158 ma-schedule-timing: A timing object indicating when the 1159 schedule fires. 1161 3.7.2. Definition of ma-action-obj 1163 object { 1164 string ma-action-name; 1165 string ma-action-task-name; 1166 [ma-option-obj ma-action-task-options<0..*>]; 1167 [ma-action-dest-obj ma-action-destinations<0..*>;] 1168 } ma-action-obj; 1170 The ma-sched-action-obj models an a task together with its schedule 1171 specific options and destination tasks. It consists of the following 1172 elements: 1174 ma-action-name: A name uniquely identifying an action of a 1175 scheduling object. 1177 ma-action-task-name: A name identifying the task to be invoked 1178 by the action. 1180 ma-action-task-options: An optional and possibly empty list of 1181 options (name-value pairs) that are passed 1182 to the task by appending them to the 1183 options configured for the task object. 1185 ma-action-destinations: An optional and possibly empty list of 1186 destination actions that consume output 1187 produced by this action. 1189 3.7.3. Definition of ma-action-dest-obj 1191 object { 1192 string ma-action-dest-schedule-name; 1193 string ma-action-dest-action-name; 1194 [int ma-action-dest-action-outputs<0..*>;] 1195 } ma-action-dest-obj; 1197 The ma-action-dest-obj defines to which subsequent actions output 1198 produced by an action should be sent to. It consists of the 1199 following elements: 1201 ma-action-dest-schedule-name: A name identifying a schedule object. 1203 ma-action-dest-action-name: A name identifying an action within a 1204 schedule object. 1206 ma-action-dest-action-outputs: An optional and possibly empty list 1207 of task outputs. If not present, the 1208 element defaults to all outputs. 1210 Example: A measurement task has two defined inter-task outputs, one 1211 for routine measurement results and one for errors during the task 1212 execution. These are defined as available outputs by the task and 1213 are denoted by the integers 1 and 2. In this example, both 1214 outputs are sent to the same reporting task called "Hourly 1215 reporting Task" that is executed from the "Hourly Schedule" 1216 schedule. This is done by creating a ma-action-dest-obj with the 1217 output selection as [1,2] and the destination action configuration 1218 name as ["Hourly Reporting Task"] and the destination schedule 1219 name as "Hourly Schedule". 1221 Measurement Task 1222 Output 1 -----+----> "Hourly Schedule":"Hourly Reporting Task" 1223 Output 2 ----/ 1225 3.8. Common Objects: Channels 1227 A Channel defines a bi-directional communication channel between the 1228 MA and a Controller or Collector. Multiple Channels can be defined 1229 to enable results to be split or duplicated across different 1230 Collectors. 1232 Each Channel contains the details of the remote endpoint (including 1233 location and security credential information such as the 1234 certificate). The timing of when to communicate over a Channel is 1235 specified by the Schedule which executes the corresponding Control or 1236 Reporting Task. The certificate can be the digital certificate 1237 associated to the FQDN in the URL or it can be the certificate of the 1238 Certification Authority that was used to issue the certificate for 1239 the FQDN (Fully Qualified Domain Name) of the target URL (which will 1240 be retrieved later on using a communication protocol such as TLS). 1241 In order to establish a secure channel, the MA will use it's own 1242 security credentials (in the Configuration Information) and the given 1243 credentials for the individual Channel end-point. 1245 As with the Task Configurations, each Channel is also given a text 1246 name by which it can be referenced as a Task Option. 1248 Although the same in terms of information, Channels used for 1249 communication with the Controller are referred to as Control Channels 1250 whereas Channels to Collectors are referred to as Report Channels. 1251 Hence Control Channels will be referenced from Control Tasks executed 1252 by a Control Schedule, whereas Report Channels will be referenced 1253 from within Reporting Tasks executed by an Instruction Schedule. 1255 Multiple interfaces are also supported. For example the Reporting 1256 Task could be configured to send some results over GPRS. This is 1257 especially useful when such results indicate the loss of connectivity 1258 on a different network interface. 1260 Example: A Channel using for reporting results may specify that 1261 results are to be sent to the URL (https://collector.foo.org/ 1262 report/), using the appropriate digital certificate to establish a 1263 secure channel.. 1265 3.8.1. Definition of ma-channel-obj 1267 object { 1268 string ma-channel-name; 1269 url ma-channel-target; 1270 credentials ma-channel-credentials; 1271 [string ma-channel-interface-name;] 1272 } ma-channel-obj; 1274 The ma-channel-obj consists of the following elements: 1276 ma-channel-name: A unique name identifying the channel 1277 object. 1279 ma-channel-target: A URL identifying the target channel 1280 endpoint. 1282 ma-channel-credentials: The security credentials needed to 1283 establish a secure channel. 1285 ma-channel-interface-name: An optional name of the network interface 1286 to be used. If not present, the system 1287 will select a suitable interface. 1289 3.9. Common Objects: Task Configurations 1291 Conceptually each Task Configuration defines the parameters of a Task 1292 that the Measurement Agent (MA) may perform at some point in time. 1293 It does not by itself actually instruct the MA to perform them at any 1294 particular time (this is done by a Schedule). Tasks can be 1295 Measurement Tasks (i.e., those Tasks actually performing some type of 1296 passive or active measurement) or any other scheduled activity 1297 performed by the MA such as transferring information to or from the 1298 Controller and Collectors. Other examples of Tasks may include data 1299 manipulation or processing Tasks conducted on the MA. 1301 A Measurement Task Configuration is the same in information terms to 1302 any other Task Configuration. Both measurement and non-measurement 1303 Tasks have a registry entry to enable the MA to uniquely identify the 1304 Task it should execute and retrieve the schema for any parameters 1305 that may be passed to the Task. This registry entry is specified as 1306 a URI and can therefore be used to identify the Task within a 1307 namespace or point to a web or local file location for the Task 1308 information. As mentioned previously this entry may be used to 1309 identify the Measurement Task in a public namespace 1310 [I-D.ietf-ippm-metric-registry] . 1312 Example: A Measurement Task Configuration may configure a single 1313 Measurement Task for measuring UDP latency. The Measurement Task 1314 Configuration could define the destination port and address for 1315 the measurement as well as the duration, internal packet timing 1316 strategy and other parameters (for example a stream for one hour 1317 and sending one packet every 500 ms). It may also define the 1318 output type and possible parameters (for example the output type 1319 can be the 95th percentile mean) where the measurement task 1320 accepts such parameters. It does not define when the task starts 1321 (this is defined by the Schedule element), so it does not by 1322 itself instruct the MA to actually perform this Measurement Task. 1324 The Task Configuration will include a local short name for reference 1325 by a Schedule. Task Configurations will also contain a registry 1326 entry as described above. In addition the Task can be configured 1327 through a set of configuration Options. The nature and number of 1328 these Options will depend upon the Task. These options are expressed 1329 as name-value pairs although the 'value' may be a structured object 1330 instead of a simple string or numeric value. The implementation of 1331 these name-value pairs will vary between data models such as JSON, 1332 XML or TR-069. 1334 A Option that must be present for Reporting Tasks is the Channel 1335 reference specifying how to communicate with a Collector. This is 1336 included in the task options and will have a value that matches a 1337 channel name that has been defined in the Instruction. Similarly 1338 Control Tasks will have a similar option with the value set to a 1339 specified Control Channel. 1341 A reporting task might also have a flag parameter to indicate whether 1342 to report if there is no measurement result data pending to be 1343 transferred to the Collector. In addition many tasks will also take 1344 as a parameter which interface to operate over. 1346 The Task Configuration also contains a suppress-by-default flag that 1347 specifies the behaviour of a default suppress instruction (that does 1348 not list explicit tasks or schedules). If this flag is set to FALSE 1349 then the Task will not be suppressed. It should be noted that 1350 Controller Tasks are not subject to the suppression instruction and 1351 therefore this flag will be ignored in such cases. 1353 In addition the Task Configuration may optionally also be given a 1354 Measurement Cycle ID. The purpose of this ID is to easily identify a 1355 set of measurement results that have been produced by Measurement 1356 Tasks with comparable Options. This ID could be manually incremented 1357 or otherwise changed when an Option change is implemented which could 1358 mean that two sets of results should not be directly compared. 1360 3.9.1. Definition of ma-task-obj 1362 object { 1363 string ma-task-name; 1364 uri ma-task-registry-entry; 1365 [ma-option-obj ma-task-options<0..*>]; 1366 [boolean ma-task-suppress-by-default;] 1367 [string ma-task-cycle-id;] 1368 } ma-task-obj; 1370 The ma-task-obj defines a task that can be invoked. A task can be 1371 referenced via its name and it contains an URI to link to a registry 1372 or a local specification of the task. Options allow the 1373 configuration of task parameter (in the form of name-value pairs). 1374 The ma-task-obj consists of the following elements: 1376 ma-task-name: A name uniquely identifying a task 1377 object. 1379 ma-task-registry-entry: A URI identifying the type of task. 1381 ma-task-options: A optional and possibly empty list of 1382 options (name-value pairs) that are 1383 passed to the task. 1385 ma-task-suppress-by-default: A boolean flag indicating whether the 1386 task will be suppressed by default. 1387 The default value of the flag is true. 1389 ma-task-cycle-id: An optional measurement cycle 1390 identifier that can be used to identify 1391 set of measurement results that have 1392 been produced by tasks with comparable 1393 options. 1395 3.9.2. Definition of ma-option-obj 1397 object { 1398 string ma-option-name; 1399 [object ma-option-value;] 1400 } ma-option-obj; 1402 The ma-option-obj models a name-value pair and consists of the 1403 following elements: 1405 ma-option-name: The name of the option. 1407 ma-option-value: The optional value of the option. 1409 While many of the Task Configuration Options are left to individual 1410 tasks to define, some common Options are used by multiple tasks and 1411 benefit from standardisation. These Options are Channel and Role. 1413 o Channel is used to specify the details of an endpoint for Control 1414 or Reporting Task communications and is detailed elsewhere in this 1415 document. The common option name for specifying the channel is 1416 "channel". 1418 o Role is used to specify which Role the task should be performing 1419 (as defined in the registry) if multiple roles are available. The 1420 common option name for specifying the role is "role". 1422 3.10. Common Objects: Timing Information 1424 The Timing information object used throughout the information models 1425 can take one of five different forms: 1427 1. Periodic. Specifies a start, end and interval time in 1428 milliseconds 1430 2. Calendar: Specifies a calendar based pattern, e.g., 22 minutes 1431 past each hour of the day on weekdays 1433 3. One Off: A single instance occurring at a specific time 1435 4. Immediate: Should occur as soon as possible 1437 5. Startup: Should occur whenever the MA is started (e.g., at device 1438 startup) 1440 Optionally each of the options may also specify a randomness that 1441 should be evaluated and applied separately to each indicated event. 1442 This randomness parameter defines a uniform interval in milliseconds 1443 over which the start of the task is delayed from the starting times 1444 specified by the timing object. 1446 Both the Periodic and Calendar timing objects allow for a series of 1447 tasks to be executed. While both have an optional end time, it is 1448 best practice to always configure an end time and refresh the 1449 information periodically to ensure that lost MAs do not continue 1450 their tasks forever. 1452 Starup timing is only executed on device startup - not when a new 1453 Instruction is transferred to the MA. If scheduled task execution is 1454 desired both on the transfer of the Instruction and on device restart 1455 then both the Immediate and Startup timing needs to be used in 1456 conjunction. 1458 The datetime format used for all elements in the information model 1459 MUST conform to RFC 3339 [RFC3339]. 1461 3.10.1. Definition of ma-timing-obj 1463 object { 1464 string ma-timing-name; 1465 union { 1466 ma-periodic-obj ma-timing-periodic; 1467 ma-calendar-obj ma-timing-calendar; 1468 ma-one-off-obj ma-timing-one-off; 1469 ma-immediate-obj ma-timing-immediate; 1470 ma-startup-obj ma-timing-startup; 1471 } 1472 [int ma-timing-random-spread;] 1473 } ma-timing-obj; 1475 The ma-timing-obj is the main timing object. Timing objects are 1476 identified by a name. The timing object itself contains a more 1477 specific timing object. These objects are further described below. 1479 The ma-timing-obj also includes an optional uniform random spread in 1480 milliseconds that can be used to randomize the start times of 1481 scheduled tasks. The ma-timing-obj consists of the following 1482 elements: 1484 ma-timing-name: The name uniquely identifies a timing 1485 object. Schedules refer to timing objects 1486 by this name. 1488 ma-timing-periodic: The ma-timing-periodic is present for 1489 periodic timing objects. 1491 ma-timing-calendar: The ma-timing-calendar is present for 1492 calendar timing objects. 1494 ma-timing-one-off: The ma-timing-one-off is present for one- 1495 off timing objects. 1497 ma-timing-immediate: The ma-timing-immediate is present for 1498 immediate timing objects. 1500 ma-timing-startup: The ma-timing-startup is present for 1501 startup timing objects. 1503 ma-timing-random-spread: The optional ma-timing-random-spread adds a 1504 random delay defined in milliseconds to the 1505 timing object. 1507 3.10.2. Definition of ma-periodic-obj 1509 object { 1510 [datetime ma-periodic-start;] 1511 [datetime ma-periodic-end;] 1512 int ma-periodic-interval; 1513 } ma-periodic-obj; 1515 The ma-periodic-obj timing object has an optional start and an 1516 optional end time plus a periodic interval. Tasks scheduled using an 1517 ma-periodic-obj are started periodically between the start and end 1518 time. The ma-periodic-obj consists of the following elements: 1520 ma-periodic-start: The optional date and time at which tasks 1521 scheduled using this object are first 1522 started. If not present it defaults to 1523 immediate. 1525 ma-periodic-end: The optional date and time at which tasks 1526 scheduled using this object last started. 1527 If not present it defaults to indefinite. 1529 ma-periodic-interval: The interval defines the time in 1530 milliseconds between two consecutive starts 1531 of tasks. 1533 3.10.3. Definition of ma-calendar-obj 1535 Calendar Timing supports the routine execution of Measurement Tasks 1536 at specific times and/or on specific dates. It can support more 1537 flexible timing than Periodic Timing since the Measurement Task 1538 execution does not have to be uniformly spaced. For example a 1539 Calendar Timing could support the execution of a Measurement Task 1540 every hour between 6pm and midnight on weekdays only. 1542 Calendar Timing is also required to perform measurements at 1543 meaningful instances in relation to network usage (e.g., at peak 1544 times). If the optional timezone offset is not supplied then local 1545 system time is assumed. This is essential in some use cases to 1546 ensure consistent peak-time measurements as well as supporting MA 1547 devices that may be in an unknown timezone or roam between different 1548 timezones (but know their own timezone information such as through 1549 the mobile network). 1551 The calendar elements within the Calendar Timing do not have defaults 1552 in order to avoid accidental high-frequency execution of Tasks. If 1553 all possible values for an element are desired then the wildcard * is 1554 used. 1556 object { 1557 [datetime ma-calendar-start;] 1558 [datetime ma-calendar-end;] 1559 [string ma-calendar-months<0..*>;] 1560 [string ma-calendar-days-of-week<0..*>;] 1561 [string ma-calendar-days-of-month<0..*>;] 1562 [string ma-calendar-hours<0..*>;] 1563 [string ma-calendar-minutes<0..*>;] 1564 [string ma-calendar-seconds<0..*>;] 1565 [int ma-calendar-timezone-offset;] 1566 } ma-calendar-obj; 1568 ma-calendar-start: The optional date and time at which 1569 tasks scheduled using this object are 1570 first started. If not present it 1571 defaults to immediate. 1573 ma-calendar-end: The optional date and time at which 1574 tasks scheduled using this object last 1575 started. If not present it defaults to 1576 indefinite. 1578 ma-calendar-months: The optional set of months (1-12) on 1579 which tasks scheduled using this object 1580 are started. The wildcard * means all 1581 months. If not present, it defaults to 1582 no months. 1584 ma-calendar-days-of-week: The optional set of days of a week 1585 ("Mon", "Tue", "Wed", "Thu", "Fri", 1586 "Sat", "Sun") on which tasks scheduled 1587 using this object are started. The 1588 wildcard * means all days of teh week. 1589 If not present, it defaults to no 1590 months. 1592 ma-calendar-days-of-month: The optional set of days of a months 1593 (1-31) on which tasks scheduled using 1594 this object are started. The wildcard 1595 * means all days of a months. If not 1596 present, it defaults to no days. 1598 ma-calendar-hours: The optional set of hours (0-23) on 1599 which tasks scheduled using this object 1600 are started. The wildcard * means all 1601 hours of a day. If not present, it 1602 defaults to no hours. 1604 ma-calendar-minutes: The optional set of minutes (0-59) on 1605 which tasks scheduled using this object 1606 are started. The wildcard * means all 1607 minutes of an hour. If not present, it 1608 defaults to no hours. 1610 ma-calendar-seconds: The optional set of seconds (0-59) on 1611 which tasks scheduled using this object 1612 are started. The wildcard * means all 1613 seconds of an hour. If not present, it 1614 defaults to no seconds. 1616 ma-calendar-timezone-offset: The optional timezone offest in hours. 1617 If not present, it defaults to the 1618 system's local timezone.. 1620 If a day of the month is specified that does not exist in the month 1621 (e.g., 29th of Feburary) then those values are ignored. 1623 3.10.4. Definition of ma-one-off-obj 1625 object { 1626 datetime ma-one-off-time; 1627 } ma-one-off-obj; 1629 The ma-one-off-obj timing object specifies a fixed point in time. 1630 Tasks scheduled using an ma-one-off-obj are started once at the 1631 specified date and time. The ma-one-off-obj consists of the 1632 following elements: 1634 ma-one-off-time: The date and time at which tasks scheduled 1635 using this object are started. 1637 3.10.5. Definition of ma-immediate-obj 1639 object { 1640 // empty 1641 } ma-immediate-obj; 1643 The ma-immediate-obj timing object has no further information 1644 elements. Tasks scheduled using an ma-immediate-obj are started as 1645 soon as possible. 1647 3.10.6. Definition of ma-startup-obj 1649 object { 1650 // empty 1651 } ma-startup-obj; 1653 The ma-startup-obj timing object has no further information elements. 1654 Tasks scheduled using an ma-startup-obj are started at MA initiation 1655 time. 1657 4. IANA Considerations 1659 This document makes no request of IANA. 1661 Note to RFC Editor: this section may be removed on publication as an 1662 RFC. 1664 5. Security Considerations 1666 This Information Model deals with information about the control and 1667 reporting of the Measurement Agent. There are broadly two security 1668 considerations for such an Information Model. Firstly the 1669 Information Model has to be sufficient to establish secure 1670 communication channels to the Controller and Collector such that 1671 other information can be sent and received securely. Additionally, 1672 any mechanisms that the Network Operator or other device 1673 administrator employs to pre-configure the MA must also be secure to 1674 protect unauthorized parties from modifying pre-configuration 1675 information. These mechanisms are important to ensure that the MA 1676 cannot be hijacked, for example to participate in a DDoS attack. 1678 The second consideration is that no mandated information items should 1679 pose a risk to confidentiality or privacy given such secure 1680 communication channels. For this latter reason items such as the MA 1681 context and MA ID are left optional and can be excluded from some 1682 deployments. This would, for example, allow the MA to remain 1683 anonymous and for information about location or other context that 1684 might be used to identify or track the MA to be omitted or blurred. 1686 The Information Model should support wherever relevant, all the 1687 security and privacy requirements associated with the LMAP Framework. 1689 6. Acknowledgements 1691 The notation was inspired by the notation used in the ALTO protocol 1692 specification. 1694 Philip Eardley, Trevor Burbridge, Marcelo Bagnulo and Juergen 1695 Schoenwaelder work in part on the Leone research project, which 1696 receives funding from the European Union Seventh Framework Programme 1697 [FP7/2007-2013] under grant agreement number 317647. 1699 7. References 1701 7.1. Normative References 1703 [I-D.ietf-lmap-framework] 1704 Eardley, P., Morton, A., Bagnulo, M., Burbridge, T., 1705 Aitken, P., and A. Akhter, "A framework for Large-Scale 1706 Measurement of Broadband Performance (LMAP)", draft-ietf- 1707 lmap-framework-12 (work in progress), March 2015. 1709 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1710 Requirement Levels", BCP 14, RFC 2119, March 1997. 1712 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 1713 Internet: Timestamps", RFC 3339, July 2002. 1715 7.2. Informative References 1717 [I-D.ietf-ippm-metric-registry] 1718 Bagnulo, M., Claise, B., Eardley, P., Morton, A., and A. 1719 Akhter, "Registry for Performance Metrics", draft-ietf- 1720 ippm-metric-registry-02 (work in progress), February 2015. 1722 [I-D.ietf-lmap-yang] 1723 Schoenwaelder, J. and V. Bajpai, "A YANG Data Model for 1724 LMAP Measurement Agents", draft-ietf-lmap-yang-00 (work 1725 in progress), April 2015. 1727 [RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between 1728 Information Models and Data Models", RFC 3444, January 1729 2003. 1731 Authors' Addresses 1733 Trevor Burbridge 1734 BT 1735 Adastral Park, Martlesham Heath 1736 Ipswich IP5 3RE 1737 United Kingdom 1739 Email: trevor.burbridge@bt.com 1741 Philip Eardley 1742 BT 1743 Adastral Park, Martlesham Heath 1744 Ipswich IP5 3RE 1745 United Kingdom 1747 Email: philip.eardley@bt.com 1749 Marcelo Bagnulo 1750 Universidad Carlos III de Madrid 1751 Av. Universidad 30 1752 Leganes, Madrid 28911 1753 Spain 1755 Email: marcelo@it.uc3m.es 1756 Juergen Schoenwaelder 1757 Jacobs University Bremen 1758 Campus Ring 1 1759 Bremen 28759 1760 Germany 1762 Email: j.schoenwaelder@jacobs-university.de