idnits 2.17.00 (12 Aug 2021) /tmp/idnits45781/draft-ietf-lmap-information-model-03.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 581 has weird spacing: '...ion-obj ma-su...' == Line 701 has weird spacing: '...ace-obj ma-...' == Line 708 has weird spacing: '...ion-obj ma-...' == Line 710 has weird spacing: '...ity-obj ma-s...' == Line 824 has weird spacing: '...ask-obj ma-re...' == (9 more instances...) -- The document date (January 05, 2015) is 2692 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 1544 -- Looks like a reference, but probably isn't: '2' on line 940 == Outdated reference: draft-ietf-lmap-framework has been published as RFC 7594 ** Downref: Normative reference to an Informational draft: draft-ietf-lmap-framework (ref. 'I-D.ietf-lmap-framework') Summary: 1 error (**), 0 flaws (~~), 9 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: July 9, 2015 M. Bagnulo 6 Universidad Carlos III de Madrid 7 J. Schoenwaelder 8 Jacobs University Bremen 9 January 05, 2015 11 Information Model for Large-Scale Measurement Platforms (LMAP) 12 draft-ietf-lmap-information-model-03 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 July 9, 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 . . . . . . . . . . . . . . . . . . . . . . . . 2 65 2. Notation . . . . . . . . . . . . . . . . . . . . . . . . . . 4 66 3. LMAP Information Model . . . . . . . . . . . . . . . . . . . 4 67 3.1. Pre-Configuration Information . . . . . . . . . . . . . . 7 68 3.2. Configuration Information . . . . . . . . . . . . . . . . 9 69 3.3. Instruction Information . . . . . . . . . . . . . . . . . 10 70 3.4. Logging Information . . . . . . . . . . . . . . . . . . . 13 71 3.5. Capability and Status Information . . . . . . . . . . . . 15 72 3.6. Reporting Information . . . . . . . . . . . . . . . . . . 16 73 3.7. Common Objects . . . . . . . . . . . . . . . . . . . . . 18 74 3.7.1. Schedules . . . . . . . . . . . . . . . . . . . . . . 18 75 3.7.2. Channels . . . . . . . . . . . . . . . . . . . . . . 21 76 3.7.3. Task Configurations . . . . . . . . . . . . . . . . . 22 77 3.7.4. Timing Information . . . . . . . . . . . . . . . . . 24 78 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 79 5. Security Considerations . . . . . . . . . . . . . . . . . . . 27 80 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 28 81 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 28 82 7.1. Normative References . . . . . . . . . . . . . . . . . . 28 83 7.2. Informative References . . . . . . . . . . . . . . . . . 28 84 Appendix A. JSON Data Model Example . . . . . . . . . . . . . . 29 85 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 37 87 1. Introduction 89 A large-scale measurement platform is a collection of components that 90 work in a coordinated fashion to perform measurements from a large 91 number of vantage points. The main components of a large-scale 92 measurement platform are the Measurement Agents (hereafter MAs), the 93 Controller(s) and the Collector(s). 95 The MAs are the elements actually performing the measurements. The 96 MAs are controlled by exactly one Controller at a time and the 97 Collectors gather the results generated by the MAs. In a nutshell, 98 the normal operation of a large-scale measurement platform starts 99 with the Controller instructing a set of one or more MAs to perform a 100 set of one or more Measurement Tasks at a certain point in time. The 101 MAs execute the instructions from a Controller, and once they have 102 done so, they report the results of the measurements to one or more 103 Collectors. The overall framework for a Large Measurement platform 104 as used in this document is described in detail in 105 [I-D.ietf-lmap-framework]. 107 A large-scale measurement platform involves basically three types of 108 protocols, namely, a Control protocol (or protocols) between a 109 Controller and the MAs, a Report protocol (or protocols) between the 110 MAs and the Collector(s) and several measurement protocols between 111 the MAs and Measurement Peers (MPs), used to actually perform the 112 measurements. In addition some information is required to be 113 configured on the MA prior to any communication with a Controller. 115 This document defines the information model for both Control and the 116 Report protocols along with pre-configuration information that is 117 required on the MA before communicating with the Controller, broadly 118 named as the LMAP Information Model. The measurement protocols are 119 out of the scope of this document. 121 As defined in [RFC3444], the LMAP Information Model (henceforth also 122 referred to as LMAP IM) defines the concepts involved in a large- 123 scale measurement platform at a high level of abstraction, 124 independent of any specific implementation or actual protocol used to 125 exchange the information. It is expected that the proposed 126 information model can be used with different protocols in different 127 measurement platform architectures and across different types of MA 128 devices (e.g., home gateway, smartphone, PC, router). 130 The definition of an Information Model serves a number of purposes: 132 1. To guide the standardisation of one or more Control and Report 133 protocols and data models 135 2. To enable high-level inter-operability between different Control 136 and Report protocols by facilitating translation between their 137 respective data models such that a Controller could instruct sub- 138 populations of MAs using different protocols 140 3. To form agreement of what information needs to be held by an MA 141 and passed over the Control and Report interfaces and support the 142 functionality described in the LMAP framework 144 4. Enable existing protocols and data models to be assessed for 145 their suitability as part of a large-scale measurement system 147 2. Notation 149 This document use an object-oriented programming-like notation to 150 define the parameters (names/values) of the objects of the 151 information model. An optional field is enclosed by [ ], and an 152 array is indicated by two numbers in angle brackets, , where m 153 indicates the minimal number of values, and n is the maximum. The 154 symbol * for n means no upper bound. 156 3. LMAP Information Model 158 The information described herein relates to the information stored, 159 received or transmitted by a Measurement Agent as described within 160 the LMAP framework [I-D.ietf-lmap-framework]. As such, some subsets 161 of this information model are applicable to the measurement 162 Controller, Collector and any device management system that pre- 163 configures the Measurement Agent. The information described in these 164 models will be transmitted by protocols using interfaces between the 165 Measurement Agent and such systems according to a Data Model. 167 For clarity the information model is divided into six sections: 169 1. Pre-Configuration Information. Information pre-configured on the 170 Measurement Agent prior to any communication with other 171 components of the LMAP architecture (i.e., the Controller, 172 Collector and Measurement Peers), specifically detailing how to 173 communicate with a Controller and whether the device is enabled 174 to participate as an MA. 176 2. Configuration Information. Update of the pre-configuration 177 information during the registration of the MA or subsequent 178 communication with the Controller, along with the configuration 179 of further parameters about the MA (rather than the Tasks it 180 should perform) that were not mandatory for the initial 181 communication between the MA and a Controller. 183 3. Instruction Information. Information that is received by the MA 184 from the Controller pertaining to the Tasks that should be 185 executed. This includes the task execution Schedules (other than 186 the Controller communication Schedule supplied as 187 (pre)configuration information) and related information such as 188 the Task Configuration, communication Channels to Collectors and 189 schedule Timing information. It also includes Task Suppression 190 information that is used to over-ride normal Task execution. 192 4. Logging Information. Information transmitted from the MA to the 193 Controller detailing the results of any configuration operations 194 along with error and status information from the operation of the 195 MA. 197 5. Capability and Status Information. Information on the general 198 status and capabilities of the MA. For example, the set of 199 measurements that are supported on the device. 201 6. Reporting Information. Information transmitted from the MA to 202 one or more Collectors including measurement results and the 203 context in which they were conducted. 205 In addition the MA may hold further information not described herein, 206 and which may be optionally transferred to or from other systems 207 including the Controller and Collector. One example of information 208 in this category is subscriber or line information that may be 209 extracted by a task and reported by the MA in the reporting 210 communication to a Collector. 212 It should also be noted that the MA may be in communication with 213 other management systems which may be responsible for configuring and 214 retrieving information from the MA device. Such systems, where 215 available, can perform an important role in transferring the pre- 216 configuration information to the MA or enabling/disabling the 217 measurement functionality of the MA. 219 The Information Model is divided into sub-sections for a number of 220 reasons. Firstly the grouping of information facilitates reader 221 understanding. Secondly, the particular groupings chosen are 222 expected to map to different protocols or different transmissions 223 within those protocols. 225 The granularity of data transmitted in each operation of the Control 226 and Report Protocols is not dictated by the Information Model. For 227 example, the Instruction object may be delivered in a single 228 operation. Alternatively, Schedules and Task Configurations may be 229 separated or even each Schedule/Task Configuration may be delivered 230 individually. Similarly the Information Model does not dictate 231 whether data is read, write, or read/write. For example, some 232 Control Protocols may have the ability to read back Configuration and 233 Instruction information which have been previosuly set on the MA. 234 Lastly, while some protocols may simply overwrite information (for 235 example refreshing the entire Instruction Information), other 236 protocols may have the ability to update or delete selected items of 237 information. 239 The information in these six sections is captured by a number of 240 common information objects. These objects are also described later 241 in this document and comprise of: 243 1. Schedules. A set of Schedules tell the MA to do something. 244 Without a Schedule no Task (from a measurement to reporting or 245 communicating with the Controller) is ever executed. Schedules 246 are used within the Instruction to specify what tasks should be 247 performed, when, and how to direct their results. A Schedule is 248 also used within the pre-Configuration and Configuration 249 information in order to execute the Task or Tasks required to 250 communicate with the Controller. 252 2. Channels. A set of Channel objects are used to communicate with 253 a number of endpoints (i.e. the Controller and Collectors). Each 254 Channel object contains the information required for the 255 communication with a single endpoint such as the target location 256 and security details. 258 3. Task Configurations. A set of Task Configurations is used to 259 configure the Tasks that are run by the MA. This includes the 260 registry entry for the Task and any configuration parameters. 261 Task Configurations are referenced from a Schedule in order to 262 specify what Tasks the MA should execute. 264 4. Timings. A set of Timing objects that can be referenced from the 265 Schedules. Each Schedule always references exactly one Timing 266 object. A Timing object specfies either a singleton or series of 267 time events. They are used to indicate when Tasks should be 268 executed. 270 The following diagram illustrates the structure in which these common 271 information objects are referenced. The references are achieved by 272 each object (Channel, Task Configuration, Timing) being given a short 273 text name that is used by other objects. The objects shown in 274 parenthesis are part of the internal object structure of a Schedule. 276 Schedule 277 |----------> Timing 278 |----------> (Scheduled Tasks) 279 |----------> Task Configuration 280 |----------> Destination Tasks 282 It should be clear that the top-level bahaviour of an MA is simply to 283 execute Schedules. Every action referenced by a Schedule is defined 284 as a Task. As such, these actions are configured through Task 285 Configurations and executed according to the Timing referenced by the 286 Schedule in which they appear. Tasks can implement a variety of 287 different types of actions. While in terms of the Information Model, 288 all Tasks have the same structure, it can help conceptually to think 289 of different Task categories: 291 1. Measurement Tasks measure some aspect of network performance or 292 traffic. They may also capture contextual information from the 293 MA device or network interfaces such the the device type or 294 available interface speed. 296 2. Data Transfer Tasks 298 A. Reporting Tasks report the results of Measurement Tasks to 299 Collectors 301 B. Control Task(s) implement the Control Protocol and 302 communicate with the Controller. Depending on the Control 303 Protocol there may be a number of specialist tasks such as: 304 Configuration Task; Instruction Task; Suppression Task; 305 Capabilities Task; Logging Task etc. 307 3. Data Analysis Tasks can exist to analyse data from other 308 Measurement Tasks locally on the MA 310 4. Data Management Tasks may exist to clean-up, filter or compress 311 data on the MA such as Measurement Task results 313 3.1. Pre-Configuration Information 315 This information is the minimal information that needs to be pre- 316 configured to the MA in order for it to successfully communicate with 317 a Controller during the registration process. Some of the Pre- 318 Configuration Information elements are repeated in the Configuration 319 Information in order to allow an LMAP Contoller to update these 320 items. The pre-configuration information also contains some elements 321 that are not under the control of the LMAP framework (such as the the 322 device identifier and device security credentials). 324 This Pre-Configuration Information needs to include a URL of the 325 initial Controller from where configuration information can be 326 communicated along with the security information required for the 327 communication including the certificate of the Controller (or the 328 certificate of the Certification Authority which was used to issue 329 the certificate for the Controller). All this is expressed as a 330 Channel. While multiple Channels may be provided in the Pre- 331 Configuration Information they must all be associated with a single 332 Controller (e.g. over different interfaces or network protocols). 334 Where the MA pulls information from the Controller, the Pre- 335 Configuration Information also needs to contain the timing of the 336 communication with the Controller as well as the nature of the 337 communication itself (such as the protocol and data to be 338 transfered). The timing is given as a Schedule that executes the 339 Task(s) responsible for communication with the Controller. It is 340 this Task (or Tasks) that implement the Control protocol between the 341 MA and the Controller and utlises the Channel information. The 342 Task(s) may take additional parameters in which case a Task 343 Configuration can also be included. 345 Even where information is pushed to the MA from the Controller 346 (rather than pulled by the MA), a Schedule still needs to be 347 supplied. In this case the Schedule will simply execute a Controller 348 listener task when the MA is started. A Channel is still required 349 for the MA to establish secure communication with the Controller. 351 It can be seen that these Channels, Schedules and Task Configurations 352 for the initial MA-Controller communication are no different in terms 353 of the Information Model to any other Channel, Schedule or Task 354 Configuration that might execute a Measurement Task or report the 355 measurement results (as described later). 357 The MA may be pre-configured with an MA ID, or may use a Device ID in 358 the first Controller contact before it is assigned an MA ID. The 359 Device ID may be a MAC address or some other device identifier 360 expressed as a URN. If the MA ID is not provided at this stage then 361 it must be provided by the Controller during Configuration. 363 Detail of the information model elements: 365 // MA pre-configuration minimal information to communicate 366 // initially with Controller 368 object { 369 [uuid ma-agent-id;] 370 ma-task-obj ma-control-tasks<1..*>; 371 ma-channel-obj ma-control-channels<1..*>; 372 ma-schedule-obj ma-control-schedules<1..*>; 373 [urn ma-device-id;] 374 credentials ma-credentials; 375 } ma-config-obj; 377 The details of the Channel and Schedule objects are described later 378 since they are common to several parts of the information model. 380 3.2. Configuration Information 382 During registration or at any later point at which the MA contacts 383 the Controller (or vice-versa), the choice of Controller, details for 384 the timing of communication with the Controller or parameters for the 385 communication Task(s) can be changed (as captured by the Channels, 386 Schedules and Task Configurations objects). For example the pre- 387 configured Controller (specified as a Channel or Channels) may be 388 over-riden with a specific Controller that is more appropriate to the 389 MA device type, location or characteristics of the network (e.g. 390 access technology type or broadband product). The initial 391 communication Schedule may be over-ridden with one more relevant to 392 routine communications between the MA and the Controller. 394 While some Control protocols may only use a single Schedule, other 395 protocolsmay use several Schedules (and related data transfer Tasks) 396 to update the Configuration Information, transfer the Instruction 397 Information, transfer Capability and Status Information and send 398 other information to the Controller such as log or error 399 notifications. Multiple Channels may be used to communicate with the 400 same Controller over multiple interfaces (e.g. to send logging 401 information over a different network). 403 In addition the MA will be given further items of information that 404 relate specifically to the MA rather than the measurements it is to 405 conduct or how to report results. The assignment of an ID to the MA 406 is mandatory. If the MA Agent ID was not optionally provided during 407 the pre-configuration then one must be provided by the Controller 408 during Configuration. Optionally a Group ID may also be given which 409 identifies a group of interest to which that MA belongs. For example 410 the group could represent an ISP, broadband product, technology, 411 market classification, geographic region, or a combination of 412 multiple such characteristics. Where the Measurement Group ID is set 413 an additional flag (the Report MA ID flag) is required to control 414 whether the Measurement Agent ID is also to be reported. The 415 reporting of a Group ID without the MA ID allows the MA to remain 416 anonymous, which may be particularly useful to prevent tracking of 417 mobile MA devices. 419 Optionally an MA can also be configured to stop executing any 420 Instruction Schedule if the Controller is unreachable. This can be 421 used as a fail-safe to stop Measurement and other Tasks being 422 conducted when there is doubt that the Instruction Information is 423 still valid. This is simply represented as a time window in 424 milliseconds since the last communication with the Controller after 425 which Instruction Schedules are to be suspended. The appropriate 426 value of the time window will depend on the specified communication 427 Schedule with the Controller and the duration for which the system is 428 willing to tolerate continued operation with potentially stale 429 Instruction Information. 431 While Pre-Configuration Information is persistent upon device reset 432 or power cycle, the persistency of the Configuration Information may 433 be device dependent. Some devices may revert back to their pre- 434 configuration state upon reboot or factory reset, while other devices 435 may store all Configuration and Instruction information in persistent 436 storage. A Controller can check whether an MA has the latest 437 Configuration and Instruction information by examing the Capability 438 and Status information for the MA. 440 It should be noted that control shedules and tasks cannot be 441 suppressed as evidenced by the lack of suppression information in the 442 Configuration. The control schedule must only reference tasks listed 443 as control tasks (i.e. within the Configuration information). Any 444 suppress-by-default flag against control tasks will be ignored. 446 Detail of the additional and updated information model elements: 448 // MA Configuration 450 object { 451 uuid ma-agent-id; 452 ma-task-obj ma-control-tasks<1..*>; 453 ma-channel-obj ma-control-channels<1..*>; 454 ma-schedule-obj ma-control-schedules<1..*>; 455 [urn ma-device-id;] 456 credentials ma-credentials; 457 [string ma-group-id;] 458 [boolean ma-report-ma-id-flag;] 459 [int ma-control-channel-failure-threshold;] 460 } ma-config-obj; 462 3.3. Instruction Information 464 The Instruction information model has four sub-elements: 466 1. Instruction Task Configurations 468 2. Report Channels 470 3. Instruction Schedules 472 4. Suppression 474 The Instruction supports the execution of all Tasks on the MA except 475 those that deal with communication with the Controller (specified in 476 (pre-)configuration information). The Tasks are configured in 477 Instruction Task Configurations and included by reference in 478 Instruction Schdules that specify when to execute them. The results 479 can be communicated to other Tasks or a Task may implement a 480 Reporting Protocol and communicate results over Report Channels. 481 Suppression is used to temporarily stop the excution of new Tasks as 482 specified by the Instruction Schedules (and optionally to stop 483 ongoing Tasks). 485 A Task Configuration is used to configure the mandatory and optional 486 parameters of a Task. It also serves to instruct the MA about the 487 Task including the ability to resolve the Task to an executable and 488 specifying the schema for the Task parameters. 490 A Report Channel defines how to communicate with a single remote 491 system specified by a URL. A Report Channel is used to send results 492 to single Collector but is no different in terms of the Information 493 Model to the Control Channel used to transfer information between the 494 MA and the Controller. Several Report Channels can be defined to 495 enable results to be split or duplicated across different 496 destinations. A single Channel can be used by multiple (reporting) 497 Task Configurations to transfer data to the same Collector. A single 498 Reporting Task Configuration can also be included in multiple 499 Schedules. E.g. a single Collector may receive data at three 500 different cycle rates, one Schedule reporting hourly, another 501 reporting daily and a third specifying that results should be sent 502 immediately for on-demand measurement tasks. Alternatively multiple 503 Report Channels can be used to send Measurement Task results to 504 different Collectors. The details of the Channel element is 505 described later as it is common to several objects. 507 Instruction Schedules specify which Tasks to execute according to a 508 given Timing (that can execute a single or repeated series of Tasks). 509 The Schedule also specifies how to link Tasks output data to other 510 scheduled Tasks - i.e. sending selected outputs to other Tasks. 512 Measurement Suppression information is used to over-ride the 513 Instruction Schedule and temporarily stop measurements or other Tasks 514 from running on the MA for a defined or indefinite period. While 515 conceptually measurements can be stopped by simply removing them from 516 the Measurement Schedule, splitting out separate information on 517 Measurement Suppression allows this information to be updated on the 518 MA on a different timing cycle or protocol implementation to the 519 Measurement Schedule. It is also considered that it will be easier 520 for a human operator to implement a temporary explicit suppression 521 rather than having to move to a reduced Schedule and then roll-back 522 at a later time. 524 The explicit Suppression instruction message is able to simply 525 enable/disable all Instruction Tasks (that are enabled for default 526 suppression) as well as having fine control on which Tasks are 527 suppressed. Suppression of both specified Task Configurations and 528 Measurement Schedules is supported. Support for disabling specific 529 Task Configurations allows malfunctioning or mis-configured Tasks or 530 Task Configurations that have an impact on a particular part of the 531 network infrastructure (e.g., a particular Measurement Peer) to be 532 targetted. Support for disabling specific Schedules allows for 533 particularly heavy cycles or sets of less essential Measurement Tasks 534 to be suppressed quickly and effectively. Note that Suppression has 535 no effect on either Controller Tasks or Controller Schedules. 537 When no tasks or schedules are explicitly listed, all Instruction 538 tasks will be suppressed (or not) as indicated by the suppress-by- 539 default flag in the Task Configuration. If tasks or schedules are 540 listed explicitly then only these listed tasks or schedules will be 541 suppressed regardless of the suppress-by-default flag. If both 542 individual tasks and individual schedules are listed then only the 543 listed schedules, plus the listed tasks where present in other 544 schedules, will be suppressed regardless of the suppress-by-default 545 flag. 547 Suppression stops new Tasks from executing. In addtion, the 548 Suppression information also supports an additional Boolean that is 549 used to select whether on-going tasks are also to be terminated. 551 Unsuppression is achieved through either overwriting the Measurement 552 Suppression information (e.g. changing 'enabled' to False) or through 553 the use of an End time such that the Measurement Suppression will no 554 longer be in effect beyond this time. The datetime format used for 555 all elements in the information model (e.g. the suppression start and 556 end dates) MUST conform to RFC 3339 [RFC3339]. 558 The goal when defining these four different elements is to allow each 559 part of the information model to change without affecting the other 560 three elements. For example it is envisaged that the Report Channels 561 and the set of Task Configurations will be relatively static. The 562 Instruction Schedule, on the other hand, is likely to be more 563 dynamic, as the measurement panel and test frequency are changed for 564 various business goals. Another example is that measurements can be 565 suppressed with a Suppression command without removing the existing 566 Instruction Schedules that would continue to apply after the 567 Suppression expires or is removed. In terms of the Controller-MA 568 communication this can reduce the data overhead. It also encourages 569 the re-use of the same standard Task Configurations and Reporting 570 Channels to help ensure consistency and reduce errors. 572 Definition of the information model elements: 574 // Instruction to the MA to configure Tasks, Channels, 575 //Schedules and Suppression 577 object { 578 ma-task-obj ma-instruction-tasks<0..*>; 579 ma-channel-obj ma-report-channels<0..*>; 580 ma-schedule-obj ma-instruction-schedules<0..*>; 581 ma-suppression-obj ma-suppression; 582 } ma-instruction-obj; 584 // Suppression object to temporarily override new task execution 585 // in Instructions and optionally stop currently running tasks 587 object { 588 boolean ma-suppression-enabled; 589 [boolean ma-suppression-stop-ongoing-tasks;] 590 // default: false 591 [datetime ma-suppression-start;] // default: immediate 592 [datetime ma-suppression-end;] // default: indefinite 593 [string ma-suppression-task-names<0..*>;] 594 // default: all tasks if 595 // ma-suppression-task-names is empty 596 [string ma-suppression-schedule-names<0..*>;] 597 // default: all schedules if 598 // ma-suppression-schedule-names is empty 599 } ma-suppression-obj; 601 3.4. Logging Information 603 The MA may report on the success or failure of Configuration or 604 Instruction communications from the Controller. In addition further 605 operational logs may be produced during the operation of the MA and 606 updates to capabilities may also be reported. Reporting this 607 information is achieved in exactly the same manner as scheduling any 608 other Task. We make no distinction between a Measurement Task 609 conducting an active or passive network measurement and one which 610 solely retrieves static or dynamic information from the MA such as 611 capabilities or logging information. One or more logging tasks can 612 be programmed or configured to capture subsets of the Logging 613 Information. These logging tasks are then executed by Schedules 614 which also specify that the resultant data is to be transferred over 615 the Controller Channels. 617 The type of Logging Information will fall into three different 618 categories: 620 1. Success/failure/warning messages in response to information 621 updates from the Controller. Failure messages could be produced 622 due to some inability to receive or parse the Controller 623 communication, or if the MA is not able to act as instructed. 624 For example: 626 * "Measurement Schedules updated OK" 628 * "Unable to parse JSON" 630 * "Missing mandatory element: Measurement Timing" 632 * "'Start' does not conform to schema - expected datetime" 634 * "Date specified is in the past" 636 * "'Hour' must be in the range 1..24" 638 * "Schedule A refers to non-existent Measurement Task 639 Configuration" 641 * "Measurement Task Configuration X registry entry Y not found" 643 * "Updated Measurement Task Configurations do not include M used 644 by Measurement Schedule N" 646 2. Operational updates from the MA. For example: 648 * "Out of memory: cannot record result" 650 * "Collector 'collector.example.com' not responding" 652 * "Unexpected restart" 654 * "Suppression timeout" 656 * "Failed to execute Measurement Task Configuration H" 658 3. Status updates from the MA. For example: 660 * "Device interface added: eth3 " 662 * "Supported measurements updated" 664 * "New IP address on eth0: xxx.xxx.xxx.xxx" 666 This Information Model document does not detail the precise format of 667 logging information since it is to a large extent protocol and MA 668 specific. However, some common information can be identified. 670 MA Logging information model elements: 672 // Logging object 674 object { 675 uuid ma-log-agent-id; 676 datetime ma-log-event-time; 677 code ma-log-code; 678 string ma-log-description; 679 } ma-log-obj; 681 3.5. Capability and Status Information 683 The MA will hold Capability Information that can be retrieved by a 684 Controller. Capabilities include the device interface details 685 available to Measurement Tasks as well as the set of Measurement 686 Tasks/Roles (specified by a registry entry) that are actually 687 installed or available on the MA. Status information includes the 688 times that operations were last performed such as contacting the 689 Controller or producing Reports. 691 MA Status information model elements: 693 // Main MA Status information object 695 object { 696 uuid ma-agent-id; 697 urn ma-device-id; 698 string ma-hardware; 699 string ma-firmware; 700 string ma-version; 701 ma-interface-obj ma-interfaces<0..*>; 703 datetime ma-last-task; 704 datetime ma-last-report; 705 datetime ma-last-instruction; 706 datetime ma-last-configuration; 708 [ma-condition-obj ma-conditions<0..*>;] 710 ma-task-capability-obj ma-supported-tasks<0..*>; 711 } ma-status-obj; 712 // Additional status conditions 714 object { 715 string ma-condition-code; 716 string ma-condition-text; 717 } ma-condition-obj 719 // Interface information 721 object { 722 string ma-interface-name; 723 string ma-interface-type; 724 [int ma-interface-speed;] // bps 725 [string ma-link-layer-address;] 726 [ip-address ma-interface-ip-addresses<0..*>]; 727 [ip-address ma-interface-gateways<0..*>;] 728 [ip-address ma-interface-dns-servers<0..*>;] 729 } ma-interface-obj; 731 // Supported tasks/roles 733 object { 734 string ma-task-name; 735 uri ma-task-registry; 736 } ma-task-capability-obj; 738 3.6. Reporting Information 740 At a point in time specified by a Schedule, the MA will execute a 741 task or tasks that communicate a set of measurement results to the 742 Collector. Some of these Tasks (notably Reporting Tasks) will 743 understand how to transmit task results over a specified Report 744 Channel to a Collector. Where to send the data is defined within the 745 Task Configuration for the Reporting Task. 747 It should be noted that the output from Tasks does not need to be 748 sent to communication Channels. It can alternatively, or 749 additionally, be sent to other Tasks on the MA. This facilitates 750 using a first Measurement Task to control the operation of a later 751 Measurement Task (such as first probing available line speed and then 752 adjusting the operation of a video testing measurement) and also to 753 allow local processing of data to output alarms (e.g. when 754 performance drops from earlier levels). Of course, subsequent Tasks 755 also include Tasks that implement the reporting protocol(s) and 756 transfer data to one or more Collector(s). 758 The report is structured hierarchically to avoid repetition of report 759 header and Measurement Task Configuration information. The report 760 starts with the timestamp of the report generation on the MA and 761 details about the MA including the optional Measurement Agent ID and 762 Group ID (controlled by the Configuration Information). 764 Much of the report Information is optional and will depend on the 765 implementation of the Reporting Task and any parameters defined in 766 the Task Configuration for the Reporting Task. For example some 767 Reporting Tasks may choose not to include the Measurement Task 768 Configuration or Sscheduled task parameters, while others may do so 769 dependent on the Controller setting a configurable parameter in the 770 Task Configuration. 772 It is possible for a Reporting Task to send just the Report header 773 (datetime and optional agent ID and/or Group ID) if no measurement 774 data is available. Whether to send such empty reports again is 775 dependent on the implementation of the Reporting Task and potential 776 Task Configuration parameter. 778 The handling of measurement data on the MA before generating a Report 779 and transfer from the MA to the Collector is dependent on the 780 implementation of the device, MA and/or scheduled Tasks and not 781 defined by the LMAP standards. Such decisions may include limits to 782 the measurement data storage and what to do when such available 783 storage becomes depleted. 785 No context information, such as line speed or broadband product are 786 included within the report header information as this data is 787 reported by individual tasks at the time they execute. Either a 788 Measurement Task can report contextual parameters that are relevant 789 to that particular measurement, or specific tasks can be used to 790 gather a set of contextual and environmental data. at certain times 791 independent of the reporting schedule. 793 After the report header information the results are reported grouped 794 according to different Measurement Task Configurations. Each Task 795 section optionally starts with replicating the Measurement Task 796 Configuration information before the result headers (titles for data 797 columns) and the result data rows. 799 The result row data includes a time for the start of the measurement 800 and optionally an end time where the duration also needs to be 801 considered in the data analysis. 803 Some Measurement Tasks may optionally include an indication of the 804 cross-traffic although the meaning a definition of cross-traffic is 805 left up to each individual Measurement Task. Some Measurement Tasks 806 may also output other environmental measures in addtion to cross- 807 traffic such as CPU utlisation or interface speed. 809 Where the Configuration and Instruction information represent 810 information transmitted via the Control Protocol, the Report 811 represents the information that is transmitted via the Report 812 Protocol. It is constructed at the time of sending a report and 813 represents the inherent structure of the information that is sent to 814 the Collector. 816 Information model elements: 818 // Main Report object with report header information 820 object { 821 datetime ma-report-date; 822 [uuid ma-report-agent-id;] 823 [string ma-report-group-id;] 824 [ma-report-task-obj ma-report-tasks<0..*>]; 825 } ma-report-obj; 827 // Report task header information 829 object { 830 string ma-report-task-name; 831 [uri ma-report-task-registry-entry;] 832 [name-value-pair ma-report-scheduled-task-options<0..*>]; 833 [string ma-report-task-cycle-id;] 834 string ma-report-task-column-labels<0..*>; 835 ma-result-row-obj ma-report-task-rows<0..*>; 836 } ma-report-task-obj; 838 // Report tasks result rows 840 object { 841 datetime ma-report-result-start-time; 842 [datetime ma-report-result-end-time;] 843 string ma-report-result-conflicting-tasks<0..*>; 844 data ma-report-result-values<0..*>; 845 } ma-result-row-obj; 847 3.7. Common Objects 849 3.7.1. Schedules 851 A Schedule specifies the execution of a single or repeated series of 852 Tasks. Each Schedule contains basically two elements: a list of 853 Tasks to be executed and a timing object for the Schedule. The 854 Schedule states what Tasks to run (with what configuration) and when 855 to run the Tasks. 857 Multiple Tasks in the list of a single Measurement Schedule will be 858 executed in order with minimal gaps. Tasks in different Schedules 859 execute in parallel with such conflicts being reported in the 860 Reporting Information. If two or more Schedules have the same start 861 time, then the two will execute in parallel. There is no mechanism 862 to prioritise one schedule over another or to mutex schduled tasks. 864 As well as specifying which Tasks to execute, the Schedule also 865 specifies how to link the data outputs from each scheduled task to 866 other scheduled tasks. Specifying this within the Schedule allows 867 the highest level of flexibility since it is even possible to send 868 the output from different executions of the same Task Configuration 869 to different destinations. Since a single Task may have multiple 870 outputs, the Schedule can independently specify which outputs go to 871 which destinations. For example, a Measurement Task might report 872 routine results to a data Reporting Task that communicates hourly via 873 the Broadband PPP interface, but also outputs emergency conditions 874 via an alarm Reporting Task communicating immediately over a GPRS 875 channel. Note that task-to-task data transfer is always specified in 876 association with the scheduled execution of the sending task - there 877 is no need for a corresponding input specification for the receiving 878 task. While it is likely that an MA implementation will use a queue 879 mechanism between the scheduled tasks, this Information Model does 880 not mandate or define a queue, or any potential associated parameters 881 such as storage size and retention policies. 883 When specifying the task to execute withi the Schedule, it is 884 possible to add to the task configuration option parameters. This 885 allows the Task Configuration to deterimine the common 886 characteristics of a Task, while selected parameters (e.g. the test 887 target URL) are defined within the schedule. A single Tasks 888 Configuration can even be used multiple times in the same schedule 889 with different additional parameters. This allows for effciency in 890 creating and transferring the Instruction. Note that the semantics 891 of what happens if an option is defined multiple times (either in the 892 Task Configuration, Schedule or in both) is not standardised and will 893 depend upon the Task. For example some tasks may legitimately take 894 multiple values for a single parameter. 896 Example: A Schedule references a single Measurement Task 897 Configuration for the UDP latency. It specifies that results are 898 to be sent to a scheduled Reporting Task. This Reporting Task is 899 executed by a separate Schedule that specifies that it should run 900 hourly at 5 minutes past the hour. When run this Reporting Task 901 takes the data generated by the UDP latency Task as well as any 902 other data to be included in the hourly report and transfers it to 903 the Collector over the Report Channel specified within its own 904 Schedule. 906 // main Schedule object with Timing and list of Scheduled Tasks 908 object { 909 string ma-schedule-name; 910 ma-sched-task-obj ma-schedule-tasks<0..*>; 911 ma-timing-obj ma-schedule-timing; 912 } ma-schedule-obj; 914 // Scheduled Task object with reference (by name string) to Task 915 // Configuration and mappings of data outputs to destination tasks 917 object { 918 string ma-schedule-task-name; 919 [name-value-pair ma-schedule-task-options<0..*>]; 920 [ma-sched-downstream-tasks-obj ma-schedule-destination-tasks<0..*>;] 921 } ma-sched-task-obj; 923 // Specification of destination scheduled tasks using reference 924 // to schedule and task configuration configuration names. Mapping 925 // of integer denoted data outputs to destination schduled task 927 object { 928 [string ma-schedule-task-destination-schedule-name]; 929 [string ma-schedule-task-destination-task-configuration-name]; 930 [int ma-schedule-task-output-selection<0..*>;] // default: all 931 } ma-sched-destination-tasks-obj; 933 Example: A measurement task has two defined inter-task outputs, one 934 for routine measurement results and one for errors during the task 935 execution. These are defined as available outputs by the task and 936 are denoted by the integers 1 & 2. In this example, both outputs 937 are sent to the same reporting task called "Hourly reporting Task" 938 that is excuted from the "Hourly Schedule" schedule. This is done 939 by creating a ma-sched-destination-tasks-obj with the output 940 selection as [1,2] and the destination task configuration name as 941 ["Hourly Reporting Task"] and the destination schedule name as 942 "Hourly Schedule". 944 Measurement Task 945 Output 1 -----+----> "Hourly Schedule":"Hourly Reporting Task" 946 Output 2 ----/ 948 3.7.2. Channels 950 A Channel defines a bi-directional communication channel between the 951 MA and a Controller or Collector. Multiple Channels can be defined 952 to enable results to be split or duplicated across different 953 Collectors. 955 Each Channel contains the details of the remote endpoint (including 956 location and security credential information such as the 957 certificate). The timing of when to communicate over a Channel is 958 specified within the Schedule. The certificate can be the digital 959 certificate associated to the FQDN in the URL or it can be the 960 certificate of the Certification Authority that was used to issue the 961 certificate for the FQDN (Fully Qualified Domain Name) of the target 962 URL (which will be retrieved later on using a communication protocol 963 such as TLS). In order to establish a secure channel, the MA will 964 use it's own security credentials (in the Configuration Information) 965 and the given credentials for the individual Channel end-point. 967 As with theTask Configurations, each Channel is also given a text 968 name by which it can be referenced from a Task Configuration. 970 Although the same in terms of information, Channels used for 971 communication with the Controller are refered to as Control Channels 972 whereas Channels to Collectors are refered to as Report Channels. 973 Hence Control Channels will be referenced from Control Tasks executed 974 by a Control Schedule, whereas Report Channels will be referenced 975 from within Reporting Tasks executed by an Instruction Schedule. 977 Multiple interfaces are also supported. For example the Controller 978 could choose to receive some results over GPRS. This is especially 979 useful when such results indicate the loss of connectivity on a 980 different network interface. 982 Example: A Channel using for reporting results may specify that 983 results are to be sent to the URL (https://collector.foo.org/ 984 report/), using the appropriate digital certificate to establish a 985 secure channel.. 987 // Channel object with name string allowing reference from Schedule. 988 // Contains channel endpoint target URL and security credentials 989 // to establish secure channel. Optionally allows interface 990 // specification (by interface name string reference) 991 // and connection when no data is pending for transfer 993 object { 994 string ma-channel-name; 995 url ma-channel-target; 996 credentials ma-channel-credentials; 997 [string ma-channel-interface-name;] 998 } ma-channel-obj; 1000 3.7.3. Task Configurations 1002 Conceptually each Task Configuration defines the parameters of a Task 1003 that the Measurement Agent (MA) may perform at some point in time. 1004 It does not by itself actually instruct the MA to perform them at any 1005 particular time (this is done by a Schedule). Tasks can be 1006 Measurement Tasks (i.e. those Tasks actually performing some type of 1007 passive or active measurement) or any other scheduled activity 1008 performed by the MA such as transferring information to or from the 1009 Controller and Collectors. Other examples of Tasks may include data 1010 manipulation or processing Tasks conducted on the MA. 1012 A Measurement Task Configuration is the same in information terms to 1013 any other Task Configuration. Both measurement and non-measurement 1014 Tasks have a registry entry to enable the MA to uniquely identify the 1015 Task it should execute and retrieve the schema for any parameters 1016 that may be passed to the Task. This registry entry is specified as 1017 a URI and can therefore be used to identify the Task within a 1018 namespace or point to a web or local file location for the Task 1019 information. As mentioned previously this entry may be used to 1020 identify the Measurement Task in a public namespace 1021 [I-D.bagnulo-ippm-new-registry] . 1023 Example: A Measurement Task Configuration may configure a single 1024 Measurement Task for measuring UDP latency. The Measurement Task 1025 Configuration could define the destination port and address for 1026 the measurement as well as the duration, internal packet timing 1027 strategy and other parameters (for example a stream for one hour 1028 and sending one packet every 500 ms). It may also define the 1029 output type and possible parameters (for example the output type 1030 can be the 95th percentile mean) where the measurement task 1031 accepts such parameters. It does not define when the task starts 1032 (this is defined by the Schedule element), so it does not by 1033 itself instruct the MA to actually perform this Measurement Task. 1035 The Task Configuration will include a local short name for reference 1036 by a Schedule. Task Configurations will also contain a registry 1037 entry as described above. In addition the Task can be configured 1038 through a set of configuration Options. The nature and number of 1039 these Options will depend upon the Task and will be resolved through 1040 the registry parameter. These options are expressed as name-value 1041 pairs although the 'value' may be a structured object instead of a 1042 simple string or numeric value. The implementation of these name- 1043 value pairs will vary between data models such as JSON, XML or TR- 1044 069. 1046 A parameter that must be present for Reporting Tasks is the Channel 1047 reference specifying how to communicate with a Collector. This is 1048 included in the task options and will have a value that matches a 1049 channel name that has been defined in the Instruction. Similarly 1050 Control Tasks will have a simialr option with the value set to a 1051 specified Control Channel. 1053 A reporting task might also have a flag parameter to indicate whether 1054 to report if there is no measurement result data pending to be 1055 transferred to the Collector. In addition many tasks will also take 1056 as a parameter which interface to operate over. 1058 The Task Configuration also contains a suppress-by-default flag that 1059 specifies the behaviour of a default suppress instruction (that does 1060 not list explicit tasks or schedules). If this flag is set to FALSE 1061 then the Task will not be suppressed. It should be noted that 1062 Controller Tasks are not subject to the suppression instruction and 1063 therefore this flag will be ignored in such cases. 1065 In addition the Task Configuration may optionally also be given a 1066 Measurement Cycle ID. The purpose of this ID is to easily identify a 1067 set of measurement results that have been produced by Measurement 1068 Tasks with comparable Options. This ID could be manually incremented 1069 or otherwise changed when an Option change is implemented which could 1070 mean that two sets of results should not be directly compared. 1072 // Task Configuration object with string name to allow reference 1073 // from Schedule. Contains URI to link to registry or local 1074 // specification of the Task. Options allow the configuration 1075 // of Task parameters (in the form of name-value pairs) 1077 object { 1078 string ma-task-name; 1079 uri ma-task-registry-entry; 1080 [name-value-pair ma-task-options<0..*>]; 1081 [boolean ma-task-suppress-by-default;] // default: TRUE 1082 [string ma-task-cycle-id;] 1083 } ma-task-obj; 1085 3.7.4. Timing Information 1087 The Timing information object used throughout the information models 1088 can take one of five different forms: 1090 1. Periodic. Specifies a start, end and interval time in 1091 milliseconds 1093 2. Calendar: Specifies a calendar based pattern - e.g. 22 minutes 1094 past each hour of the day on weekdays 1096 3. One Off: A single instance occurring at a specific time 1098 4. Immediate: Should occur as soon as possible 1100 5. Startup: Should occur whenever the MA is started (e.g. at device 1101 startup) 1103 Optionally each of the options may also specify a randomness that 1104 should be evaluated and applied separately to each indicated event. 1105 This randomness parameter defines a uniform interval in milliseconds 1106 over which the start of the task is delayed from the starting times 1107 specified by the timing object. 1109 Both the Periodic and Calendar timing objects allow for a series of 1110 tasks to be executed. While both have an optional end time, it is 1111 best practice to always configure an end time and refresh the 1112 information periodically to ensure that lost MAs do not continue 1113 their tasks forever. 1115 Starup timing is only excuted on device startup - not when a new 1116 Instruction is transferred to the MA. If scheduled task execution is 1117 desired both on the transfer of the Instruction and on device restart 1118 then both the Immediate and Starup timing needs to be used in 1119 conjunction. 1121 The datetime format used for all elements in the information model 1122 MUST conform to RFC 3339 [RFC3339]. 1124 // Main Timing object with name string to allow reference by Schedule 1125 // Must be specialised by one of the Timing options. 1126 // Includes optional uniform random spread in ms from start time 1127 // given by Timing specialisation 1129 object { 1130 [string ma-timing-name;] 1131 union { 1132 ma-periodic-obj ma-timing-periodic; 1133 ma-calendar-obj ma-timing-calendar; 1134 ma-one-off-obj ma-timing-one-off; 1135 ma-immediate-obj ma-timing-immediate; 1136 ma-startup-obj ma-timing-startup; 1137 } 1138 [int ma-timing-random-spread;] // milliseconds 1139 } ma-timing-obj; 1141 3.7.4.1. Periodic Timing 1143 Information model elements: 1145 // Timing specialisation to run a series of Tasks repeated at 1146 // set intervals 1148 object { 1149 [datetime ma-periodic start;] // default: immediate 1150 [datetime ma-periodic-end;] // default: indefinite 1151 int ma-periodic-interval; // milliseconds 1152 } ma-periodic-obj; 1154 3.7.4.2. Calendar Timing 1156 Calendar Timing supports the routine execution of Measurement Tasks 1157 at specific times and/or on specific dates. It can support more 1158 flexible timing than Periodic Timing since the Measurement Task 1159 execution does not have to be uniformly spaced. For example a 1160 Calendar Timing could support the execution of a Measurement Task 1161 every hour between 6pm and midnight on weekdays only. 1163 Calendar Timing is also required to perform measurements at 1164 meaningful instances in relation to network usage (e.g., at peak 1165 times). If the optional timezone offset is not supplied then local 1166 system time is assumed. This is essential in some use cases to 1167 ensure consistent peak-time measurements as well as supporting MA 1168 devices that may be in an unknown timezone or roam between different 1169 timezones (but know their own timezone information such as through 1170 the mobile network). 1172 Days of week are define using three character strings "Mon", "Tue", 1173 "Wed", "Thu", "Fri", "Sat", "Sun". 1175 If a day of the month is specified that does not exist in the month 1176 (e.g. 29 in Feburary) then those values are ignored. 1178 The calendar elements within the Calendar Timing do not have defaults 1179 in order to avoid accidental high-frequency execution of Tasks. If 1180 all possible values for an element are desired then the wildcard * is 1181 used. 1183 Information model elements: 1185 // Timing specialisation to run repeated Tasks at specific 1186 // times and/or days 1188 object { 1189 [datetime ma-calendar-start;] // default: immediate 1190 [datetime ma-calendar-end;] // default: indefinite 1191 [int ma-calendar-months<0..*>;] // values: 1-12,* 1192 [days ma-calendar-days-of-week<0..*>;] 1193 // values: "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun",* 1194 [int ma-calendar-days-of-month<0..*>;] // values 1-31,* 1195 [int ma-calendar-hours<0..*>;] // values: 0-23,* 1196 [int ma-calendar-minutes<0..*>;] // values: 0-59,* 1197 [int ma-calendar-seconds<0..*>;] // values: 0-59,* 1198 [int ma-calendar-timezone-offset;] 1199 // default: system timezone offset 1200 } ma-calendar-obj; 1202 3.7.4.3. One-Off Timing 1204 Information model elements: 1206 // Timing specialisation to run once at a specified time/date 1208 object { 1209 datetime ma-one-off-time; 1210 } ma-one-off-obj; 1212 3.7.4.4. Immediate Timing 1214 The immediate timing object has no further information elements. The 1215 measurement or report is simply to be done as soon as possible. 1217 // Timing specialisation to run immediately 1219 object { 1220 // empty 1221 } ma-immediate-obj; 1223 3.7.4.5. Startup Timing 1225 The immediate timing object has no further information elements. The 1226 measurement or report is simply done at MA initiation. 1228 // Timing specialisation to run at MA startup 1230 object { 1231 // empty 1232 } ma-startup-obj; 1234 4. IANA Considerations 1236 This document makes no request of IANA. 1238 Note to RFC Editor: this section may be removed on publication as an 1239 RFC. 1241 5. Security Considerations 1243 This Information Model deals with information about the control and 1244 reporting of the Measurement Agent. There are broadly two security 1245 considerations for such an Information Model. Firstly the 1246 Information Model has to be sufficient to establish secure 1247 communication channels to the Controller and Collector such that 1248 other information can be sent and received securely. Additionally, 1249 any mechanisms that the Network Operator or other device 1250 administrator employs to pre-configure the MA must also be secure to 1251 protect unauthorized parties from modifying pre-configuration 1252 information. These mechanisms are important to ensure that the MA 1253 cannot be hijacked, for example to particpate in a DDoS attack. 1255 The second consideration is that no mandated information items should 1256 pose a risk to confidentiality or privacy given such secure 1257 communication channels. For this latter reason items such as the MA 1258 context and MA ID are left optional and can be excluded from some 1259 deployments. This would, for example, allow the MA to remain 1260 anonymous and for information about location or other context that 1261 might be used to identify or track the MA to be omitted or blurred. 1263 The Information Model should support wherever relevant, all the 1264 security and privacy requirements associated with the LMAP Framework. 1266 6. Acknowledgements 1268 The notation was inspired by the notation used in the ALTO protocol 1269 specification. 1271 Philip Eardley, Trevor Burbridge, Marcelo Bagnulo and Juergen 1272 Schoenwaelder work in part on the Leone research project, which 1273 receives funding from the European Union Seventh Framework Programme 1274 [FP7/2007-2013] under grant agreement number 317647. 1276 7. References 1278 7.1. Normative References 1280 [I-D.ietf-lmap-framework] 1281 Eardley, P., Morton, A., Bagnulo, M., Burbridge, T., 1282 Aitken, P., and A. Akhter, "A framework for large-scale 1283 measurement platforms (LMAP)", draft-ietf-lmap- 1284 framework-03 (work in progress), January 2014. 1286 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1287 Requirement Levels", BCP 14, RFC 2119, March 1997. 1289 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 1290 Internet: Timestamps", RFC 3339, July 2002. 1292 7.2. Informative References 1294 [I-D.bagnulo-ippm-new-registry] 1295 Bagnulo, M., Burbridge, T., Crawford, S., Eardley, P., and 1296 A. Morton, "A registry for commonly used metrics", draft- 1297 bagnulo-ippm-new-registry-01 (work in progress), July 1298 2013. 1300 [RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between 1301 Information Models and Data Models", RFC 3444, January 1302 2003. 1304 Appendix A. JSON Data Model Example 1306 In order to give an example of data in the Information Model we need 1307 to select a data model language. In this example we have expressed 1308 the Data Model using JSON as this will be of direct interest to some 1309 Control and Report Protocols. The example is broken down into a 1310 number of different steps that might adhere to the steps within a 1311 Control and Report Protocol: 1313 1. Pre-configuration. 1315 2. Configuration 1317 3. Capabilities 1319 4. Instruction 1321 5. Report 1323 6. Suppression 1325 While the pre-configuration is not delivered as part of the Control 1326 Protocol, the same JSON data model is used for consistency and to aid 1327 the reader. 1329 //Pre-configuration 1331 { 1332 "ma-config": { 1333 "ma-agent-id": "550e8400-e29b-41d4-a716-446655440000", 1334 "ma-control-tasks": [ 1335 { 1336 "ma-task-name": "Controller configuration", 1337 "ma-task-registry-entry": 1338 "urn:ietf:lmap:control:http_controller_configuration", 1339 "ma-task-options": [{"name": "channel", 1340 "value": "Controller channel"}] 1341 } 1342 ], 1343 "ma-control-channels": [ 1344 { 1345 "ma-channel-name": "Controller channel", 1346 "ma-channel-target": "http://www.example.com/lmap/controller", 1347 "ma-channel-credientials": { } 1348 } 1349 ], 1350 "ma-control-schedules": [ 1351 { 1352 "ma-schedule-name": "pre-configured schedule", 1353 "ma-schedule-tasks": { 1355 "ma-schedule-task-name": "Controller configuration", 1356 }, 1357 "ma-schedule-timing": { 1358 "ma-timing-name": "startup plus up to one hour", 1359 "ma-timing-startup": { 1360 }, 1361 "ma-timing-random-spread": "3600000" 1362 } 1363 } 1364 ], 1365 "ma-credentials": { } 1366 } 1367 } 1369 Given the pre-configuration information the MA is able to contact the 1370 Controller and receive an updated/expanded Configuration. In this 1371 example additional Control Protocol tasks to post Status and 1372 Capabilities to the Controller and fetch the Instruction are added as 1373 well as moving the schedule timing for contacting the Controller to 1374 hourly. 1376 // Configuration 1378 { 1379 "ma-config": { 1380 "ma-agent-id": "550e8400-e29b-41d4-a716-446655440000", 1381 "ma-control-tasks": [ 1382 { 1383 "ma-task-name": "Controller configuration", 1384 "ma-task-registry-entry": 1385 "urn:ietf:lmap:control:http_controller_configuration", 1386 "ma-task-options": [{"name": "channel", 1387 "value": "Controller channel"}] 1388 }, 1389 { 1390 "ma-task-name": "Controller status and capabilities", 1391 "ma-task-registry-entry": 1392 "urn:ietf:lmap:control:http_control_status_and_capabilities", 1393 "ma-task-options": [{"name": "channel", 1394 "value": "Controller channel"}] 1395 }, 1396 { 1397 "ma-task-name": "Controller instruction", 1398 "ma-task-registry-entry": 1399 "urn:ietf:lmap:control:http_controller_instruction", 1400 "ma-task-options": [{"name": "channel", 1401 "value": "Controller channel"}] 1402 } 1403 ], 1404 "ma-control-channels": [ 1405 { 1406 "ma-channel-name": "Controller channel", 1407 "ma-channel-target": "http://www.example.com/lmap/controller", 1408 "ma-channel-credientials": { } 1409 } 1410 ], 1411 "ma-control-schedules": [ 1412 { 1413 "ma-schedule-name": "Controller schedule", 1414 "ma-schedule-tasks": [ 1415 { 1416 "ma-schedule-task-name": "Controller configuration", 1417 }, 1418 { 1419 "ma-schedule-task-name": 1420 "Controller status and capabilities", 1422 }, 1423 { 1424 "ma-schedule-task-name": "Controller instruction", 1425 } 1426 ], 1427 "ma-schedule-timing": { 1428 "ma-timing-name": "hourly randomly", 1429 "ma-timing-calendar": { 1430 "ma-calendar-minutes": ["00"], 1431 "ma-calendar-seconds": ["00"] 1432 }, 1433 "ma-timing-random-spread": "3600000" 1434 } 1435 } 1436 ], 1437 "ma-credentials": { } 1438 } 1439 } 1441 The above configuration now contacts the Controller randomnly within 1442 each hour. The following is an example of the Status and 1443 Capabilities information that is transferred from the MA to the 1444 Controller. 1446 // Status and Capabilities 1448 { 1449 "ma-status-and-capabilities": { 1450 "ma-agent-id": "550e8400-e29b-41d4-a716-446655440000", 1451 "ma-device-id": "urn:dev:mac:0024befffe804ff1", 1452 "ma-hardware": "mfr-home-gateway-v10", 1453 "ma-firmware": "25637748-rev2a", 1454 "ma-version": "ispa-v1.01", 1455 "ma-interfaces": [ 1456 { 1457 "ma-interface-name": "broadband", 1458 "ma-interface-type": "PPPoE" 1459 } 1460 ], 1461 "ma-last-task": "", 1462 "ma-last-report": "", 1463 "ma-last-instruction": "", 1464 "ma-last-configuration": "2014-06-08T22:47:31+00:00", 1465 "ma-supported-tasks": [ 1466 { 1467 "ma-task-name": "Controller configuration", 1468 "ma-task-registry": 1469 "urn:ietf:lmap:control:http_controller_configuration" 1470 },, 1471 { 1472 "ma-task-name": "Controller status and capabilities", 1473 "ma-task-registry": 1474 "urn:ietf:lmap:control:http_control_status_and_capabilities" 1475 }, 1476 { 1477 "ma-task-name": "Controller instruction", 1478 "ma-task-registry": 1479 "urn:ietf:lmap:control:http_controller_instruction" 1480 }, 1481 { 1482 "ma-task-name": "Report", 1483 "ma-task-registry": "urn:ietf:lmap:report:http_report" 1484 }, 1485 { 1486 "ma-task-name": "UDP Latency", 1487 "ma-task-registry": 1488 "urn:ietf:ippm:measurement:UDPLatency-Poisson-XthPercMean" 1489 } 1490 ] 1491 } 1492 } 1494 After fetching the status and capabilties the Controller issues and 1495 Instruction to the MA to perform a single UDP latency measurement 1496 task 4 times a day and to report the results immediately. 1498 // Instruction 1500 { 1501 "ma-instruction": { 1502 "ma-instruction-tasks": [ 1503 { 1504 "ma-task-name": "UDP Latency", 1505 "ma-task-registry-entry": 1506 "urn:ietf:ippm:measurement:UDPLatency-Poisson-XthPercMean", 1507 "ma-task-options": [ 1508 {"name": "X", "value": "99"}, 1509 {"name":"rate", "value": "5"}, 1510 {"name":"duration", "value": "30.000"}, 1511 {"name":"interface", "value": "broadband"}, 1512 {"name":"destination-ip", 1513 "value": {"version":"ipv4", "ip-address":"192.168.2.54"}}, 1514 {"name":"destination-port", "value": "50000"}, 1515 {"name":"source-port", "value": "50000"} 1516 ], 1517 "ma-task-suppress-by-default": "TRUE" 1518 }, 1519 { 1520 "ma-task-name": "Report", 1521 "ma-task-registry-entry": "urn:ietf:lmap:report:http_report", 1522 "ma-task-options": [ 1523 {"name": "report-with-no-data", "value": "FALSE"}, 1524 {"name": "channel", "value": "Collector A"]} 1525 ], 1526 "ma-task-suppress-by-default": "FALSE" 1527 } 1528 ], 1529 "ma-report-channels": [ 1530 { 1531 "ma-channel-name": "Collector A", 1532 "ma-channel-target": "http://www.example2.com/lmap/collector", 1533 "ma-channel-credientials": { } 1534 } 1535 ], 1536 "ma-instruction-schedules": [ 1537 { 1538 "ma-schedule-name": "4 times daily test UDP latency and report", 1539 "ma-schedule-tasks": [ 1540 { 1541 "ma-schedule-task-name": "UDP Latency", 1542 "ma-schedule-destination-tasks": [ 1543 { 1544 "ma-schedule-task-output-selection": [1], 1545 "ma-schedule-task-destination-schedule-name": 1546 "4 times daily test UDP latency and report", 1547 "ma-schedule-task-destination-task-configuration-names": 1548 "Report" 1549 } 1550 ] 1551 }, 1552 { 1553 "ma-schedule-task-name": "Report", 1554 } 1555 ], 1557 "ma-schedule-timing": { 1558 "ma-timing-name": "once every 6 hours", 1559 "ma-timing-calendar": { 1560 "ma-calendar-hours": ["00", "06", "12", "18"], 1561 "ma-calendar-minutes": ["00"], 1562 "ma-calendar-seconds": ["00"] 1563 }, 1564 "ma-timing-random-spread": "21600000" 1565 } 1566 } 1567 ] 1568 } 1569 } 1571 The report task in the Instruction is executed immediately after the 1572 UDP test and transfers the following data to the Collector. 1574 // Report 1576 { 1577 "ma-report": { 1578 "ma-report-date": "2014-06-09T02:30:45+00:00", 1579 "ma-report-agent-id": "550e8400-e29b-41d4-a716-446655440000", 1580 "ma-report-tasks": [ 1581 { 1582 "ma-report-task-name": "UDP Latency", 1583 "ma-report-task-registry-entry": 1584 "urn:ietf:ippm:measurement:UDPLatency-Poisson-XthPercMean", 1585 "ma-report-scheduled-task-options": [ 1586 {"name": "X", "value": "99"}, 1587 {"name":"rate", "value": "5"}, 1588 {"name":"duration", "value": "30.000"}, 1589 {"name":"interface", "value": "broadband"}, 1590 {"name":"destination-ip", 1591 "value": {"version":"ipv4", "ip-address":"192.168.2.54"}}, 1592 {"name":"destination-port", "value": "50000"}, 1593 {"name":"source-port", "value": "50000"} 1594 ], 1595 "ma-report-task-column-labels": 1596 ["start-time", "conflicting-tasks", "cross-traffic", 1597 "mean", "min", "max"], 1598 "ma-report-task-rows": 1599 ["2014-06-09T02:30:10+00:00", "", "0", 1600 "20.13", "18.3", "24.1"] 1601 } 1602 ] 1603 } 1604 } 1606 The Controller decides that there is a problem with the UDP L:atency 1607 test and issues a Suppression Instruction. Since the task is marked 1608 as suppressable by default, simply turning on suppression will stop 1609 the task being executed in future. 1611 // Suppression 1613 { 1614 "ma-instruction": { 1615 "ma-suppression": { 1616 "ma-suppression-enabled": "TRUE" 1617 } 1618 } 1619 } 1621 Authors' Addresses 1623 Trevor Burbridge 1624 BT 1625 Adastral Park, Martlesham Heath 1626 Ipswich IP5 3RE 1627 United Kingdom 1629 Email: trevor.burbridge@bt.com 1631 Philip Eardley 1632 BT 1633 Adastral Park, Martlesham Heath 1634 Ipswich IP5 3RE 1635 United Kingdom 1637 Email: philip.eardley@bt.com 1639 Marcelo Bagnulo 1640 Universidad Carlos III de Madrid 1641 Av. Universidad 30 1642 Leganes, Madrid 28911 1643 Spain 1645 Email: marcelo@it.uc3m.es 1646 Juergen Schoenwaelder 1647 Jacobs University Bremen 1648 Campus Ring 1 1649 Bremen 28759 1650 Germany 1652 Email: j.schoenwaelder@jacobs-university.de