idnits 2.17.1 draft-ietf-lmap-information-model-04.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 584 has weird spacing: '...ion-obj ma-su...' == Line 705 has weird spacing: '...ity-obj ma-su...' == Line 721 has weird spacing: '...ion-obj ma-...' == Line 842 has weird spacing: '...ask-obj ma-re...' == Line 852 has weird spacing: '...row-obj ma-r...' == (8 more instances...) -- The document date (March 5, 2015) is 3330 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 1604 -- Looks like a reference, but probably isn't: '2' on line 961 == Outdated reference: A later version (-14) exists of draft-ietf-lmap-framework-10 ** 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-01 Summary: 1 error (**), 0 flaws (~~), 10 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: September 6, 2015 M. Bagnulo 6 Universidad Carlos III de Madrid 7 J. Schoenwaelder 8 Jacobs University Bremen 9 March 5, 2015 11 Information Model for Large-Scale Measurement Platforms (LMAP) 12 draft-ietf-lmap-information-model-04 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 September 6, 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 . . . . . . . . . . . . . . . . . . . . . 19 74 3.7.1. Schedules . . . . . . . . . . . . . . . . . . . . . . 19 75 3.7.2. Channels . . . . . . . . . . . . . . . . . . . . . . 21 76 3.7.3. Task Configurations . . . . . . . . . . . . . . . . . 22 77 3.7.4. Timing Information . . . . . . . . . . . . . . . . . 25 78 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 79 5. Security Considerations . . . . . . . . . . . . . . . . . . . 28 80 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 29 81 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 29 82 7.1. Normative References . . . . . . . . . . . . . . . . . . 29 83 7.2. Informative References . . . . . . . . . . . . . . . . . 29 84 Appendix A. JSON Data Model Example . . . . . . . . . . . . . . 30 85 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 38 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 previously 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 (Task Configuration, Timing) being given a short text 273 name that is used by other objects. The objects shown in parenthesis 274 are part of the internal object structure of a Schedule. Channels 275 are not shown in the diagram since they are only used as an option by 276 selected Task Configurations but are similarly referenced using a 277 short text name. 279 Schedule 280 |----------> Timing 281 |----------> (Scheduled Tasks) 282 |----------> Task Configuration 283 |----------> Destination Tasks 285 It should be clear that the top-level bahaviour of an MA is simply to 286 execute Schedules. Every action referenced by a Schedule is defined 287 as a Task. As such, these actions are configured through Task 288 Configurations and executed according to the Timing referenced by the 289 Schedule in which they appear. Tasks can implement a variety of 290 different types of actions. While in terms of the Information Model, 291 all Tasks have the same structure, it can help conceptually to think 292 of different Task categories: 294 1. Measurement Tasks measure some aspect of network performance or 295 traffic. They may also capture contextual information from the 296 MA device or network interfaces such as the device type or 297 interface speed. 299 2. Data Transfer Tasks 301 A. Reporting Tasks report the results of Measurement Tasks to 302 Collectors 304 B. Control Task(s) implement the Control Protocol and 305 communicate with the Controller. Depending on the Control 306 Protocol there may be a number of specialist tasks such as: 307 Configuration Task; Instruction Task; Suppression Task; 308 Capabilities Task; Logging Task etc. 310 3. Data Analysis Tasks can exist to analyse data from other 311 Measurement Tasks locally on the MA 313 4. Data Management Tasks may exist to clean-up, filter or compress 314 data on the MA such as Measurement Task results 316 3.1. Pre-Configuration Information 318 This information is the minimal information that needs to be pre- 319 configured to the MA in order for it to successfully communicate with 320 a Controller during the registration process. Some of the Pre- 321 Configuration Information elements are repeated in the Configuration 322 Information in order to allow an LMAP Controller to update these 323 items. The pre-configuration information also contains some elements 324 that are not under the control of the LMAP framework (such as the 325 device identifier and device security credentials). 327 This Pre-Configuration Information needs to include a URL of the 328 initial Controller from where configuration information can be 329 communicated along with the security information required for the 330 communication including the certificate of the Controller (or the 331 certificate of the Certification Authority which was used to issue 332 the certificate for the Controller). All this is expressed as a 333 Channel. While multiple Channels may be provided in the Pre- 334 Configuration Information they must all be associated with a single 335 Controller (e.g. over different interfaces or network protocols). 337 Where the MA pulls information from the Controller, the Pre- 338 Configuration Information also needs to contain the timing of the 339 communication with the Controller as well as the nature of the 340 communication itself (such as the protocol and data to be 341 transferred). The timing is given as a Schedule that executes the 342 Task(s) responsible for communication with the Controller. It is 343 this Task (or Tasks) that implement the Control protocol between the 344 MA and the Controller and utilises the Channel information. The 345 Task(s) may take additional parameters in which case a Task 346 Configuration can also be included. 348 Even where information is pushed to the MA from the Controller 349 (rather than pulled by the MA), a Schedule still needs to be 350 supplied. In this case the Schedule will simply execute a Controller 351 listener task when the MA is started. A Channel is still required 352 for the MA to establish secure communication with the Controller. 354 It can be seen that these Channels, Schedules and Task Configurations 355 for the initial MA-Controller communication are no different in terms 356 of the Information Model to any other Channel, Schedule or Task 357 Configuration that might execute a Measurement Task or report the 358 measurement results (as described later). 360 The MA may be pre-configured with an MA ID, or may use a Device ID in 361 the first Controller contact before it is assigned an MA ID. The 362 Device ID may be a MAC address or some other device identifier 363 expressed as a URN. If the MA ID is not provided at this stage then 364 it must be provided by the Controller during Configuration. 366 Detail of the information model elements: 368 // MA pre-configuration minimal information to communicate 369 // initially with Controller 371 object { 372 [uuid ma-agent-id;] 373 ma-task-obj ma-control-tasks<1..*>; 374 ma-channel-obj ma-control-channels<1..*>; 375 ma-schedule-obj ma-control-schedules<1..*>; 376 [urn ma-device-id;] 377 credentials ma-credentials; 378 } ma-config-obj; 380 The details of the Channel and Schedule objects are described later 381 since they are common to several parts of the information model. 383 3.2. Configuration Information 385 During registration or at any later point at which the MA contacts 386 the Controller (or vice-versa), the choice of Controller, details for 387 the timing of communication with the Controller or parameters for the 388 communication Task(s) can be changed (as captured by the Channels, 389 Schedules and Task Configurations objects). For example the pre- 390 configured Controller (specified as a Channel or Channels) may be 391 over-ridden with a specific Controller that is more appropriate to 392 the MA device type, location or characteristics of the network (e.g. 393 access technology type or broadband product). The initial 394 communication Schedule may be over-ridden with one more relevant to 395 routine communications between the MA and the Controller. 397 While some Control protocols may only use a single Schedule, other 398 protocols may use several Schedules (and related data transfer Tasks) 399 to update the Configuration Information, transfer the Instruction 400 Information, transfer Capability and Status Information and send 401 other information to the Controller such as log or error 402 notifications. Multiple Channels may be used to communicate with the 403 same Controller over multiple interfaces (e.g. to send logging 404 information over a different network). 406 In addition the MA will be given further items of information that 407 relate specifically to the MA rather than the measurements it is to 408 conduct or how to report results. The assignment of an ID to the MA 409 is mandatory. If the MA Agent ID was not optionally provided during 410 the pre-configuration then one must be provided by the Controller 411 during Configuration. Optionally a Group ID may also be given which 412 identifies a group of interest to which that MA belongs. For example 413 the group could represent an ISP, broadband product, technology, 414 market classification, geographic region, or a combination of 415 multiple such characteristics. Where the Measurement Group ID is set 416 an additional flag (the Report MA ID flag) is required to control 417 whether the Measurement Agent ID is also to be reported. The 418 reporting of a Group ID without the MA ID allows the MA to remain 419 anonymous, which may be particularly useful to prevent tracking of 420 mobile MA devices. 422 Optionally an MA can also be configured to stop executing any 423 Instruction Schedule if the Controller is unreachable. This can be 424 used as a fail-safe to stop Measurement and other Tasks being 425 conducted when there is doubt that the Instruction Information is 426 still valid. This is simply represented as a time window in 427 milliseconds since the last communication with the Controller after 428 which Instruction Schedules are to be suspended. The appropriate 429 value of the time window will depend on the specified communication 430 Schedule with the Controller and the duration for which the system is 431 willing to tolerate continued operation with potentially stale 432 Instruction Information. 434 While Pre-Configuration Information is persistent upon device reset 435 or power cycle, the persistency of the Configuration Information may 436 be device dependent. Some devices may revert back to their pre- 437 configuration state upon reboot or factory reset, while other devices 438 may store all Configuration and Instruction information in persistent 439 storage. A Controller can check whether an MA has the latest 440 Configuration and Instruction information by examining the Capability 441 and Status information for the MA. 443 It should be noted that control shcedules and tasks cannot be 444 suppressed as evidenced by the lack of suppression information in the 445 Configuration. The control schedule must only reference tasks listed 446 as control tasks (i.e. within the Configuration information). Any 447 suppress-by-default flag against control tasks will be ignored. 449 Detail of the additional and updated information model elements: 451 // MA Configuration 453 object { 454 uuid ma-agent-id; 455 ma-task-obj ma-control-tasks<1..*>; 456 ma-channel-obj ma-control-channels<1..*>; 457 ma-schedule-obj ma-control-schedules<1..*>; 458 [urn ma-device-id;] 459 credentials ma-credentials; 460 [string ma-group-id;] 461 [boolean ma-report-ma-id-flag;] 462 [int ma-control-channel-failure-threshold;] 463 } ma-config-obj; 465 3.3. Instruction Information 467 The Instruction information model has four sub-elements: 469 1. Instruction Task Configurations 471 2. Report Channels 473 3. Instruction Schedules 475 4. Suppression 477 The Instruction supports the execution of all Tasks on the MA except 478 those that deal with communication with the Controller (specified in 479 (pre-)configuration information). The Tasks are configured in 480 Instruction Task Configurations and included by reference in 481 Instruction Schedules that specify when to execute them. The results 482 can be communicated to other Tasks or a Task may implement a 483 Reporting Protocol and communicate results over Report Channels. 484 Suppression is used to temporarily stop the execution of new Tasks as 485 specified by the Instruction Schedules (and optionally to stop 486 ongoing Tasks). 488 A Task Configuration is used to configure the mandatory and optional 489 parameters of a Task. It also serves to instruct the MA about the 490 Task including the ability to resolve the Task to an executable and 491 specifying the schema for the Task parameters. 493 A Report Channel defines how to communicate with a single remote 494 system specified by a URL. A Report Channel is used to send results 495 to single Collector but is no different in terms of the Information 496 Model to the Control Channel used to transfer information between the 497 MA and the Controller. Several Report Channels can be defined to 498 enable results to be split or duplicated across different 499 destinations. A single Channel can be used by multiple (reporting) 500 Task Configurations to transfer data to the same Collector. A single 501 Reporting Task Configuration can also be included in multiple 502 Schedules. E.g. a single Collector may receive data at three 503 different cycle rates, one Schedule reporting hourly, another 504 reporting daily and a third specifying that results should be sent 505 immediately for on-demand measurement tasks. Alternatively multiple 506 Report Channels can be used to send Measurement Task results to 507 different Collectors. The details of the Channel element is 508 described later as it is common to several objects. 510 Instruction Schedules specify which Tasks to execute according to a 511 given Timing (that can execute a single or repeated series of Tasks). 512 The Schedule also specifies how to link Tasks output data to other 513 scheduled Tasks - i.e. sending selected outputs to other Tasks. 515 Measurement Suppression information is used to over-ride the 516 Instruction Schedule and temporarily stop measurements or other Tasks 517 from running on the MA for a defined or indefinite period. While 518 conceptually measurements can be stopped by simply removing them from 519 the Measurement Schedule, splitting out separate information on 520 Measurement Suppression allows this information to be updated on the 521 MA on a different timing cycle or protocol implementation to the 522 Measurement Schedule. It is also considered that it will be easier 523 for a human operator to implement a temporary explicit suppression 524 rather than having to move to a reduced Schedule and then roll-back 525 at a later time. 527 The explicit Suppression instruction message is able to simply 528 enable/disable all Instruction Tasks (that are enabled for default 529 suppression) as well as having fine control on which Tasks are 530 suppressed. Suppression of both specified Task Configurations and 531 Measurement Schedules is supported. Support for disabling specific 532 Task Configurations allows malfunctioning or mis-configured Tasks or 533 Task Configurations that have an impact on a particular part of the 534 network infrastructure (e.g., a particular Measurement Peer) to be 535 targeted. Support for disabling specific Schedules allows for 536 particularly heavy cycles or sets of less essential Measurement Tasks 537 to be suppressed quickly and effectively. Note that Suppression has 538 no effect on either Controller Tasks or Controller Schedules. 540 When no tasks or schedules are explicitly listed, all Instruction 541 tasks will be suppressed (or not) as indicated by the suppress-by- 542 default flag in the Task Configuration. If tasks or schedules are 543 listed explicitly then only these listed tasks or schedules will be 544 suppressed regardless of the suppress-by-default flag. If both 545 individual tasks and individual schedules are listed then only the 546 listed schedules, plus the listed tasks where present in other 547 schedules, will be suppressed regardless of the suppress-by-default 548 flag. 550 Suppression stops new Tasks from executing. In addition, the 551 Suppression information also supports an additional Boolean that is 552 used to select whether on-going tasks are also to be terminated. 554 Unsuppression is achieved through either overwriting the Measurement 555 Suppression information (e.g. changing 'enabled' to False) or through 556 the use of an End time such that the Measurement Suppression will no 557 longer be in effect beyond this time. The datetime format used for 558 all elements in the information model (e.g. the suppression start and 559 end dates) MUST conform to RFC 3339 [RFC3339]. 561 The goal when defining these four different elements is to allow each 562 part of the information model to change without affecting the other 563 three elements. For example it is envisaged that the Report Channels 564 and the set of Task Configurations will be relatively static. The 565 Instruction Schedule, on the other hand, is likely to be more 566 dynamic, as the measurement panel and test frequency are changed for 567 various business goals. Another example is that measurements can be 568 suppressed with a Suppression command without removing the existing 569 Instruction Schedules that would continue to apply after the 570 Suppression expires or is removed. In terms of the Controller-MA 571 communication this can reduce the data overhead. It also encourages 572 the re-use of the same standard Task Configurations and Reporting 573 Channels to help ensure consistency and reduce errors. 575 Definition of the information model elements: 577 // Instruction to the MA to configure Tasks, Channels, 578 //Schedules and Suppression 580 object { 581 ma-task-obj ma-instruction-tasks<0..*>; 582 ma-channel-obj ma-report-channels<0..*>; 583 ma-schedule-obj ma-instruction-schedules<0..*>; 584 ma-suppression-obj ma-suppression; 585 } ma-instruction-obj; 587 // Suppression object to temporarily override new task execution 588 // in Instructions and optionally stop currently running tasks 590 object { 591 boolean ma-suppression-enabled; 592 [boolean ma-suppression-stop-ongoing-tasks;] 593 // default: false 594 [datetime ma-suppression-start;] // default: immediate 595 [datetime ma-suppression-end;] // default: indefinite 596 [string ma-suppression-task-names<0..*>;] 597 // default: all tasks if 598 // ma-suppression-task-names is empty 599 [string ma-suppression-schedule-names<0..*>;] 600 // default: all schedules if 601 // ma-suppression-schedule-names is empty 602 } ma-suppression-obj; 604 3.4. Logging Information 606 The MA may report on the success or failure of Configuration or 607 Instruction communications from the Controller. In addition further 608 operational logs may be produced during the operation of the MA and 609 updates to capabilities may also be reported. Reporting this 610 information is achieved in exactly the same manner as scheduling any 611 other Task. We make no distinction between a Measurement Task 612 conducting an active or passive network measurement and one which 613 solely retrieves static or dynamic information from the MA such as 614 capabilities or logging information. One or more logging tasks can 615 be programmed or configured to capture subsets of the Logging 616 Information. These logging tasks are then executed by Schedules 617 which also specify that the resultant data is to be transferred over 618 the Controller Channels. 620 The type of Logging Information will fall into three different 621 categories: 623 1. Success/failure/warning messages in response to information 624 updates from the Controller. Failure messages could be produced 625 due to some inability to receive or parse the Controller 626 communication, or if the MA is not able to act as instructed. 627 For example: 629 * "Measurement Schedules updated OK" 631 * "Unable to parse JSON" 633 * "Missing mandatory element: Measurement Timing" 635 * "'Start' does not conform to schema - expected datetime" 637 * "Date specified is in the past" 639 * "'Hour' must be in the range 1..24" 641 * "Schedule A refers to non-existent Measurement Task 642 Configuration" 644 * "Measurement Task Configuration X registry entry Y not found" 646 * "Updated Measurement Task Configurations do not include M used 647 by Measurement Schedule N" 649 2. Operational updates from the MA. For example: 651 * "Out of memory: cannot record result" 653 * "Collector 'collector.example.com' not responding" 655 * "Unexpected restart" 657 * "Suppression timeout" 659 * "Failed to execute Measurement Task Configuration H" 661 3. Status updates from the MA. For example: 663 * "Device interface added: eth3 " 665 * "Supported measurements updated" 667 * "New IP address on eth0: xxx.xxx.xxx.xxx" 669 This Information Model document does not detail the precise format of 670 logging information since it is to a large extent protocol and MA 671 specific. However, some common information can be identified. 673 MA Logging information model elements: 675 // Logging object 677 object { 678 uuid ma-log-agent-id; 679 datetime ma-log-event-time; 680 code ma-log-code; 681 string ma-log-description; 682 } ma-log-obj; 684 3.5. Capability and Status Information 686 The MA will hold Capability Information that can be retrieved by a 687 Controller. Capabilities include the device interface details 688 available to Measurement Tasks as well as the set of Measurement 689 Tasks/Roles (specified by a registry entry) that are actually 690 installed or available on the MA. Status information includes the 691 times that operations were last performed such as contacting the 692 Controller or producing Reports. 694 MA Status information model elements: 696 // Main MA Status information object 698 object { 699 uuid ma-agent-id; 700 urn ma-device-id; 701 string ma-hardware; 702 string ma-firmware; 703 string ma-version; 704 ma-interface-obj ma-interfaces<0..*>; 705 ma-task-capability-obj ma-supported-tasks<0..*>; 706 datetime ma-last-started; 707 [ma-condition-obj ma-conditions<0..*>;] 708 [ma-task-status-obj ma-task-status<0..*>;] 709 } ma-status-obj; 710 // Per-Task status information and conditions 712 object { 713 string ma-task-name; 714 string ma-task-role; 715 uri ma-task-registry; 716 datetime ma-task-last-invocation; 717 datetime ma-task-last-successful; 718 string ma-task-last-successful-message; 719 datetime ma-task-last-failed; 720 string ma-task-last-failed-message; 721 [ma-condition-obj ma-task-conditions<0..*>]; 722 } ma-task-status-obj 724 // Additional status conditions 726 object { 727 int ma-condition-code; 728 string ma-condition-text; 729 } ma-condition-obj 731 // Interface information 733 object { 734 string ma-interface-name; 735 string ma-interface-type; 736 [int ma-interface-speed;] // bps 737 [string ma-link-layer-address;] 738 [ip-address ma-interface-ip-addresses<0..*>]; 739 [ip-address ma-interface-gateways<0..*>;] 740 [ip-address ma-interface-dns-servers<0..*>;] 741 } ma-interface-obj; 743 // Supported tasks/roles 745 object { 746 string ma-task-name; 747 string ma-task-role; 748 uri ma-task-registry; 749 } ma-task-capability-obj; 751 3.6. Reporting Information 753 At a point in time specified by a Schedule, the MA will execute a 754 task or tasks that communicate a set of measurement results to the 755 Collector. These Reporting Tasks will be configured to transmit task 756 results over a specified Report Channel to a Collector. 758 It should be noted that the output from Tasks does not need to be 759 sent to communication Channels. It can alternatively, or 760 additionally, be sent to other Tasks on the MA. This facilitates 761 using a first Measurement Task to control the operation of a later 762 Measurement Task (such as first probing available line speed and then 763 adjusting the operation of a video testing measurement) and also to 764 allow local processing of data to output alarms (e.g. when 765 performance drops from earlier levels). Of course, subsequent Tasks 766 also include Tasks that implement the reporting protocol(s) and 767 transfer data to one or more Collector(s). 769 The Report generated by a Reporting Task is structured hierarchically 770 to avoid repetition of report header and Measurement Task 771 Configuration information. The report starts with the timestamp of 772 the report generation on the MA and details about the MA including 773 the optional Measurement Agent ID and Group ID (controlled by the 774 Configuration Information). 776 Much of the report Information is optional and will depend on the 777 implementation of the Reporting Task and any parameters defined in 778 the Task Configuration for the Reporting Task. For example some 779 Reporting Tasks may choose not to include the Measurement Task 780 Configuration or scheduled task parameters, while others may do so 781 dependent on the Controller setting a configurable parameter in the 782 Task Configuration. 784 It is possible for a Reporting Task to send just the Report header 785 (datetime and optional agent ID and/or Group ID) if no measurement 786 data is available. Whether to send such empty reports again is 787 dependent on the implementation of the Reporting Task and potential 788 Task Configuration parameter. 790 The handling of measurement data on the MA before generating a Report 791 and transfer from the MA to the Collector is dependent on the 792 implementation of the device, MA and/or scheduled Tasks and not 793 defined by the LMAP standards. Such decisions may include limits to 794 the measurement data storage and what to do when such available 795 storage becomes depleted. 797 No context information, such as line speed or broadband product are 798 included within the report header information as this data is 799 reported by individual tasks at the time they execute. Either a 800 Measurement Task can report contextual parameters that are relevant 801 to that particular measurement, or specific tasks can be used to 802 gather a set of contextual and environmental data. at certain times 803 independent of the reporting schedule. 805 After the report header information the results are reported grouped 806 according to different Measurement Task Configurations. Each Task 807 section optionally starts with replicating the Measurement Task 808 Configuration information before the result headers (titles for data 809 columns) and the result data rows. The Options reported are those 810 used for the scheduled execution of the Measurement Task and 811 therefore include the Options specified in the Task Configuration as 812 well as additional Options specified in the Scheduled Task. The 813 Scheduled Task Options are appended to the Task Configuration Options 814 in exactly the same order as they were provided to the Task during 815 execution. 817 The result row data includes a time for the start of the measurement 818 and optionally an end time where the duration also needs to be 819 considered in the data analysis. 821 Some Measurement Tasks may optionally include an indication of the 822 cross-traffic although the meaning a definition of cross-traffic is 823 left up to each individual Measurement Task. Some Measurement Tasks 824 may also output other environmental measures in addition to cross- 825 traffic such as CPU utlilisation or interface speed. 827 Where the Configuration and Instruction information represent 828 information transmitted via the Control Protocol, the Report 829 represents the information that is transmitted via the Report 830 Protocol. It is constructed at the time of sending a report and 831 represents the inherent structure of the information that is sent to 832 the Collector. 834 Information model elements: 836 // Main Report object with report header information 838 object { 839 datetime ma-report-date; 840 [uuid ma-report-agent-id;] 841 [string ma-report-group-id;] 842 [ma-report-task-obj ma-report-tasks<0..*>]; 843 } ma-report-obj; 844 // Report task header information 846 object { 847 string ma-report-task-name; 848 [uri ma-report-task-registry-entry;] 849 [name-value-pair ma-report-scheduled-task-options<0..*>]; 850 [string ma-report-task-cycle-id;] 851 string ma-report-task-column-labels<0..*>; 852 ma-result-row-obj ma-report-task-rows<0..*>; 853 } ma-report-task-obj; 855 // Report tasks result rows 857 object { 858 datetime ma-report-result-start-time; 859 [datetime ma-report-result-end-time;] 860 string ma-report-result-conflicting-tasks<0..*>; 861 data ma-report-result-values<0..*>; 862 } ma-result-row-obj; 864 3.7. Common Objects 866 3.7.1. Schedules 868 A Schedule specifies the execution of a single or repeated series of 869 Tasks. Each Schedule contains basically two elements: a list of 870 Tasks to be executed and a timing object for the Schedule. The 871 Schedule states what Tasks to run (with what configuration) and when 872 to run the Tasks. 874 Multiple Tasks in the list of a single Measurement Schedule will be 875 executed in order with minimal gaps. Tasks in different Schedules 876 execute in parallel with such conflicts being reported in the 877 Reporting Information. If two or more Schedules have the same start 878 time, then the two will execute in parallel. There is no mechanism 879 to prioritise one schedule over another or to mutex scheduled tasks. 881 As well as specifying which Tasks to execute, the Schedule also 882 specifies how to link the data outputs from each scheduled task to 883 other scheduled tasks. Specifying this within the Schedule allows 884 the highest level of flexibility since it is even possible to send 885 the output from different executions of the same Task Configuration 886 to different destinations. Since a single Task may have multiple 887 outputs, the Schedule can independently specify which outputs go to 888 which destinations. For example, a Measurement Task might report 889 routine results to a data Reporting Task that communicates hourly via 890 the Broadband PPP interface, but also outputs emergency conditions 891 via an alarm Reporting Task communicating immediately over a GPRS 892 channel. Note that task-to-task data transfer is always specified in 893 association with the scheduled execution of the sending task - there 894 is no need for a corresponding input specification for the receiving 895 task. While it is likely that an MA implementation will use a queue 896 mechanism between the scheduled tasks, this Information Model does 897 not mandate or define a queue, or any potential associated parameters 898 such as storage size and retention policies. 900 When specifying the task to execute within the Schedule, it is 901 possible to add to the task configuration option parameters. This 902 allows the Task Configuration to determine the common characteristics 903 of a Task, while selected parameters (e.g. the test target URL) are 904 defined within the schedule. A single Tasks Configuration can even 905 be used multiple times in the same schedule with different additional 906 parameters. This allows for efficiency in creating and transferring 907 the Instruction. Note that the semantics of what happens if an 908 option is defined multiple times (either in the Task Configuration, 909 Schedule or in both) is not standardised and will depend upon the 910 Task. For example, some tasks may legitimately take multiple values 911 for a single parameter. 913 Where Options are specified in both the Schedule and the Task 914 Configuration, the Schedule Options are appended to those specified 915 in the Task Configuration. 917 Example: A Schedule references a single Measurement Task 918 Configuration for the UDP latency. It specifies that results are 919 to be sent to a scheduled Reporting Task. This Reporting Task is 920 executed by a separate Schedule that specifies that it should run 921 hourly at 5 minutes past the hour. When run this Reporting Task 922 takes the data generated by the UDP latency Task as well as any 923 other data to be included in the hourly report and transfers it to 924 the Collector over the Report Channel specified within its own 925 Schedule. 927 // main Schedule object with Timing and list of Scheduled Tasks 929 object { 930 string ma-schedule-name; 931 ma-sched-task-obj ma-schedule-tasks<0..*>; 932 ma-timing-obj ma-schedule-timing; 933 } ma-schedule-obj; 935 // Scheduled Task object with reference (by name string) to Task 936 // Configuration and mappings of data outputs to destination tasks 938 object { 939 string ma-schedule-task-name; 940 [name-value-pair ma-schedule-task-options<0..*>]; 941 [ma-sched-downstream-tasks-obj ma-schedule-destination-tasks<0..*>;] 942 } ma-sched-task-obj; 944 // Specification of destination scheduled tasks using reference 945 // to schedule and task configuration names. Mapping of 946 // integer denoted data outputs to destination scheduled task 948 object { 949 [string ma-schedule-task-destination-schedule-name]; 950 [string ma-schedule-task-destination-task-configuration-name]; 951 [int ma-schedule-task-output-selection<0..*>;] // default: all 952 } ma-sched-destination-tasks-obj; 954 Example: A measurement task has two defined inter-task outputs, one 955 for routine measurement results and one for errors during the task 956 execution. These are defined as available outputs by the task and 957 are denoted by the integers 1 & 2. In this example, both outputs 958 are sent to the same reporting task called "Hourly reporting Task" 959 that is executed from the "Hourly Schedule" schedule. This is 960 done by creating a ma-sched-destination-tasks-obj with the output 961 selection as [1,2] and the destination task configuration name as 962 ["Hourly Reporting Task"] and the destination schedule name as 963 "Hourly Schedule". 965 Measurement Task 966 Output 1 -----+----> "Hourly Schedule":"Hourly Reporting Task" 967 Output 2 ----/ 969 3.7.2. Channels 971 A Channel defines a bi-directional communication channel between the 972 MA and a Controller or Collector. Multiple Channels can be defined 973 to enable results to be split or duplicated across different 974 Collectors. 976 Each Channel contains the details of the remote endpoint (including 977 location and security credential information such as the 978 certificate). The timing of when to communicate over a Channel is 979 specified by the Schedule which executes the corresponding Control or 980 Reporting Task. The certificate can be the digital certificate 981 associated to the FQDN in the URL or it can be the certificate of the 982 Certification Authority that was used to issue the certificate for 983 the FQDN (Fully Qualified Domain Name) of the target URL (which will 984 be retrieved later on using a communication protocol such as TLS). 985 In order to establish a secure channel, the MA will use it's own 986 security credentials (in the Configuration Information) and the given 987 credentials for the individual Channel end-point. 989 As with the Task Configurations, each Channel is also given a text 990 name by which it can be referenced as a Task Option. 992 Although the same in terms of information, Channels used for 993 communication with the Controller are referred to as Control Channels 994 whereas Channels to Collectors are referred to as Report Channels. 995 Hence Control Channels will be referenced from Control Tasks executed 996 by a Control Schedule, whereas Report Channels will be referenced 997 from within Reporting Tasks executed by an Instruction Schedule. 999 Multiple interfaces are also supported. For example the Reporting 1000 Task could be configured to send some results over GPRS. This is 1001 especially useful when such results indicate the loss of connectivity 1002 on a different network interface. 1004 Example: A Channel using for reporting results may specify that 1005 results are to be sent to the URL (https://collector.foo.org/ 1006 report/), using the appropriate digital certificate to establish a 1007 secure channel.. 1009 // Channel object with name string allowing reference. 1010 // Contains channel endpoint target URL and security credentials 1011 // to establish secure channel. Optionally allows interface 1012 // specification (by interface name string reference) 1014 object { 1015 string ma-channel-name; 1016 url ma-channel-target; 1017 credentials ma-channel-credentials; 1018 [string ma-channel-interface-name;] 1019 } ma-channel-obj; 1021 3.7.3. Task Configurations 1023 Conceptually each Task Configuration defines the parameters of a Task 1024 that the Measurement Agent (MA) may perform at some point in time. 1025 It does not by itself actually instruct the MA to perform them at any 1026 particular time (this is done by a Schedule). Tasks can be 1027 Measurement Tasks (i.e. those Tasks actually performing some type of 1028 passive or active measurement) or any other scheduled activity 1029 performed by the MA such as transferring information to or from the 1030 Controller and Collectors. Other examples of Tasks may include data 1031 manipulation or processing Tasks conducted on the MA. 1033 A Measurement Task Configuration is the same in information terms to 1034 any other Task Configuration. Both measurement and non-measurement 1035 Tasks have a registry entry to enable the MA to uniquely identify the 1036 Task it should execute and retrieve the schema for any parameters 1037 that may be passed to the Task. This registry entry is specified as 1038 a URI and can therefore be used to identify the Task within a 1039 namespace or point to a web or local file location for the Task 1040 information. As mentioned previously this entry may be used to 1041 identify the Measurement Task in a public namespace 1042 [I-D.ietf-ippm-metric-registry] . 1044 Example: A Measurement Task Configuration may configure a single 1045 Measurement Task for measuring UDP latency. The Measurement Task 1046 Configuration could define the destination port and address for 1047 the measurement as well as the duration, internal packet timing 1048 strategy and other parameters (for example a stream for one hour 1049 and sending one packet every 500 ms). It may also define the 1050 output type and possible parameters (for example the output type 1051 can be the 95th percentile mean) where the measurement task 1052 accepts such parameters. It does not define when the task starts 1053 (this is defined by the Schedule element), so it does not by 1054 itself instruct the MA to actually perform this Measurement Task. 1056 The Task Configuration will include a local short name for reference 1057 by a Schedule. Task Configurations will also contain a registry 1058 entry as described above. In addition the Task can be configured 1059 through a set of configuration Options. The nature and number of 1060 these Options will depend upon the Task. These options are expressed 1061 as name-value pairs although the 'value' may be a structured object 1062 instead of a simple string or numeric value. The implementation of 1063 these name-value pairs will vary between data models such as JSON, 1064 XML or TR-069. 1066 A Option that must be present for Reporting Tasks is the Channel 1067 reference specifying how to communicate with a Collector. This is 1068 included in the task options and will have a value that matches a 1069 channel name that has been defined in the Instruction. Similarly 1070 Control Tasks will have a similar option with the value set to a 1071 specified Control Channel. 1073 A reporting task might also have a flag parameter to indicate whether 1074 to report if there is no measurement result data pending to be 1075 transferred to the Collector. In addition many tasks will also take 1076 as a parameter which interface to operate over. 1078 The Task Configuration also contains a suppress-by-default flag that 1079 specifies the behaviour of a default suppress instruction (that does 1080 not list explicit tasks or schedules). If this flag is set to FALSE 1081 then the Task will not be suppressed. It should be noted that 1082 Controller Tasks are not subject to the suppression instruction and 1083 therefore this flag will be ignored in such cases. 1085 In addition the Task Configuration may optionally also be given a 1086 Measurement Cycle ID. The purpose of this ID is to easily identify a 1087 set of measurement results that have been produced by Measurement 1088 Tasks with comparable Options. This ID could be manually incremented 1089 or otherwise changed when an Option change is implemented which could 1090 mean that two sets of results should not be directly compared. 1092 // Task Configuration object with string name to allow reference 1093 // from Schedule. Contains URI to link to registry or local 1094 // specification of the Task. Options allow the configuration 1095 // of Task parameters (in the form of name-value pairs) 1097 object { 1098 string ma-task-name; 1099 uri ma-task-registry-entry; 1100 [ma-task-option ma-task-options<0..*>]; 1101 [boolean ma-task-suppress-by-default;] // default: TRUE 1102 [string ma-task-cycle-id;] 1103 } ma-task-obj; 1105 While many of the Task Configuration Options are left to individual 1106 tasks to define, some common Options are used by multiple tasks and 1107 benefit from standardisation. These Options are Channel and Role. 1109 Channel is used to specify the details of an endpoint for Control or 1110 Reporting Task communications and is detailed elsewhere in this 1111 document. 1113 Role is used to specify which Role the task should be performing (as 1114 defined in the registry) if multiple roles are available. 1116 // General Task Option 1118 object { 1119 string ma-option-name; 1120 object ma-option-value; 1121 } ma-task-option 1123 // Channel Option 1125 oobject { 1126 string ma-option-name; // set to "channel" 1127 string ma-option-value; // set to ma-channel-name reference 1128 } ma-task-option 1130 // Role Option 1132 object { 1133 string ma-option-name; // set to "role" 1134 string ma-option-value; // set to registry role reference 1135 } ma-task-option 1137 3.7.4. Timing Information 1139 The Timing information object used throughout the information models 1140 can take one of five different forms: 1142 1. Periodic. Specifies a start, end and interval time in 1143 milliseconds 1145 2. Calendar: Specifies a calendar based pattern - e.g. 22 minutes 1146 past each hour of the day on weekdays 1148 3. One Off: A single instance occurring at a specific time 1150 4. Immediate: Should occur as soon as possible 1152 5. Startup: Should occur whenever the MA is started (e.g. at device 1153 startup) 1155 Optionally each of the options may also specify a randomness that 1156 should be evaluated and applied separately to each indicated event. 1157 This randomness parameter defines a uniform interval in milliseconds 1158 over which the start of the task is delayed from the starting times 1159 specified by the timing object. 1161 Both the Periodic and Calendar timing objects allow for a series of 1162 tasks to be executed. While both have an optional end time, it is 1163 best practice to always configure an end time and refresh the 1164 information periodically to ensure that lost MAs do not continue 1165 their tasks forever. 1167 Starup timing is only executed on device startup - not when a new 1168 Instruction is transferred to the MA. If scheduled task execution is 1169 desired both on the transfer of the Instruction and on device restart 1170 then both the Immediate and Startup timing needs to be used in 1171 conjunction. 1173 The datetime format used for all elements in the information model 1174 MUST conform to RFC 3339 [RFC3339]. 1176 // Main Timing object with name string to allow reference by Schedule 1177 // Must be specialised by one of the Timing options. 1178 // Includes optional uniform random spread in ms from start time 1179 // given by Timing specialisation 1181 object { 1182 [string ma-timing-name;] 1183 union { 1184 ma-periodic-obj ma-timing-periodic; 1185 ma-calendar-obj ma-timing-calendar; 1186 ma-one-off-obj ma-timing-one-off; 1187 ma-immediate-obj ma-timing-immediate; 1188 ma-startup-obj ma-timing-startup; 1189 } 1190 [int ma-timing-random-spread;] // milliseconds 1191 } ma-timing-obj; 1193 3.7.4.1. Periodic Timing 1195 Information model elements: 1197 // Timing specialisation to run a series of Tasks repeated at 1198 // set intervals 1200 object { 1201 [datetime ma-periodic start;] // default: immediate 1202 [datetime ma-periodic-end;] // default: indefinite 1203 int ma-periodic-interval; // milliseconds 1204 } ma-periodic-obj; 1206 3.7.4.2. Calendar Timing 1208 Calendar Timing supports the routine execution of Measurement Tasks 1209 at specific times and/or on specific dates. It can support more 1210 flexible timing than Periodic Timing since the Measurement Task 1211 execution does not have to be uniformly spaced. For example a 1212 Calendar Timing could support the execution of a Measurement Task 1213 every hour between 6pm and midnight on weekdays only. 1215 Calendar Timing is also required to perform measurements at 1216 meaningful instances in relation to network usage (e.g., at peak 1217 times). If the optional timezone offset is not supplied then local 1218 system time is assumed. This is essential in some use cases to 1219 ensure consistent peak-time measurements as well as supporting MA 1220 devices that may be in an unknown timezone or roam between different 1221 timezones (but know their own timezone information such as through 1222 the mobile network). 1224 Days of week are define using three character strings "Mon", "Tue", 1225 "Wed", "Thu", "Fri", "Sat", "Sun". 1227 If a day of the month is specified that does not exist in the month 1228 (e.g. 29 in Feburary) then those values are ignored. 1230 The calendar elements within the Calendar Timing do not have defaults 1231 in order to avoid accidental high-frequency execution of Tasks. If 1232 all possible values for an element are desired then the wildcard * is 1233 used. 1235 Information model elements: 1237 // Timing specialisation to run repeated Tasks at specific 1238 // times and/or days 1240 object { 1241 [datetime ma-calendar-start;] // default: immediate 1242 [datetime ma-calendar-end;] // default: indefinite 1243 [int ma-calendar-months<0..*>;] // values: 1-12,* 1244 [days ma-calendar-days-of-week<0..*>;] 1245 // values: "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun",* 1246 [int ma-calendar-days-of-month<0..*>;] // values 1-31,* 1247 [int ma-calendar-hours<0..*>;] // values: 0-23,* 1248 [int ma-calendar-minutes<0..*>;] // values: 0-59,* 1249 [int ma-calendar-seconds<0..*>;] // values: 0-59,* 1250 [int ma-calendar-timezone-offset;] 1251 // default: system timezone offset 1252 } ma-calendar-obj; 1254 3.7.4.3. One-Off Timing 1256 Information model elements: 1258 // Timing specialisation to run once at a specified time/date 1260 object { 1261 datetime ma-one-off-time; 1262 } ma-one-off-obj; 1264 3.7.4.4. Immediate Timing 1266 The immediate timing object has no further information elements. The 1267 measurement or report is simply to be done as soon as possible. 1269 // Timing specialisation to run immediately 1271 object { 1272 // empty 1273 } ma-immediate-obj; 1275 3.7.4.5. Startup Timing 1277 The immediate timing object has no further information elements. The 1278 measurement or report is simply done at MA initiation. 1280 // Timing specialisation to run at MA startup 1282 object { 1283 // empty 1284 } ma-startup-obj; 1286 4. IANA Considerations 1288 This document makes no request of IANA. 1290 Note to RFC Editor: this section may be removed on publication as an 1291 RFC. 1293 5. Security Considerations 1295 This Information Model deals with information about the control and 1296 reporting of the Measurement Agent. There are broadly two security 1297 considerations for such an Information Model. Firstly the 1298 Information Model has to be sufficient to establish secure 1299 communication channels to the Controller and Collector such that 1300 other information can be sent and received securely. Additionally, 1301 any mechanisms that the Network Operator or other device 1302 administrator employs to pre-configure the MA must also be secure to 1303 protect unauthorized parties from modifying pre-configuration 1304 information. These mechanisms are important to ensure that the MA 1305 cannot be hijacked, for example to participate in a DDoS attack. 1307 The second consideration is that no mandated information items should 1308 pose a risk to confidentiality or privacy given such secure 1309 communication channels. For this latter reason items such as the MA 1310 context and MA ID are left optional and can be excluded from some 1311 deployments. This would, for example, allow the MA to remain 1312 anonymous and for information about location or other context that 1313 might be used to identify or track the MA to be omitted or blurred. 1315 The Information Model should support wherever relevant, all the 1316 security and privacy requirements associated with the LMAP Framework. 1318 6. Acknowledgements 1320 The notation was inspired by the notation used in the ALTO protocol 1321 specification. 1323 Philip Eardley, Trevor Burbridge, Marcelo Bagnulo and Juergen 1324 Schoenwaelder work in part on the Leone research project, which 1325 receives funding from the European Union Seventh Framework Programme 1326 [FP7/2007-2013] under grant agreement number 317647. 1328 7. References 1330 7.1. Normative References 1332 [I-D.ietf-lmap-framework] 1333 Eardley, P., Morton, A., Bagnulo, M., Burbridge, T., 1334 Aitken, P., and A. Akhter, "A framework for large-scale 1335 measurement platforms (LMAP)", draft-ietf-lmap- 1336 framework-10 (work in progress), January 2015. 1338 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1339 Requirement Levels", BCP 14, RFC 2119, March 1997. 1341 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 1342 Internet: Timestamps", RFC 3339, July 2002. 1344 7.2. Informative References 1346 [I-D.ietf-ippm-metric-registry] 1347 Bagnulo, M., Claise, B., Eardley, P., Morton, A., and A. 1348 Akhter, "Registry for Performance Metrics", draft-ietf- 1349 ippm-metric-registry-01 (work in progress), September 1350 2014. 1352 [I-D.schoenw-lmap-yang] 1353 Schoenwaelder, J. and V. Bajpai, "A YANG Data Model for 1354 LMAP Measurement Agents", draft-schoenw-lmap-yang-02 (work 1355 in progress), January 2015. 1357 [RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between 1358 Information Models and Data Models", RFC 3444, January 1359 2003. 1361 Appendix A. JSON Data Model Example 1363 In order to give an example of data in the Information Model we need 1364 to select a data model language. In the following example we have 1365 expressed the Data Model using JSON as this will be of direct 1366 interest to some Control and Report Protocols. A YANG data model 1367 implementation of the Information Model is provided in a separate 1368 draft [I-D.schoenw-lmap-yang]. 1370 The example is broken down into a number of different steps that 1371 might adhere to the steps within a Control and Report Protocol: 1373 1. Pre-configuration. 1375 2. Configuration 1377 3. Capabilities 1379 4. Instruction 1381 5. Report 1383 6. Suppression 1385 While the pre-configuration is not delivered as part of the Control 1386 Protocol, the same JSON data model is used for consistency and to aid 1387 the reader. 1389 //Pre-configuration 1391 { 1392 "ma-config": { 1393 "ma-agent-id": "550e8400-e29b-41d4-a716-446655440000", 1394 "ma-control-tasks": [ 1395 { 1396 "ma-task-name": "Controller configuration", 1397 "ma-task-registry-entry": 1398 "urn:ietf:lmap:control:http_controller_configuration", 1399 "ma-task-options": [{"name": "channel", 1400 "value": "Controller channel"}] 1401 } 1402 ], 1403 "ma-control-channels": [ 1404 { 1405 "ma-channel-name": "Controller channel", 1406 "ma-channel-target": "http://www.example.com/lmap/controller", 1407 "ma-channel-credientials": { } 1408 } 1409 ], 1410 "ma-control-schedules": [ 1411 { 1412 "ma-schedule-name": "pre-configured schedule", 1413 "ma-schedule-tasks": { 1415 "ma-schedule-task-name": "Controller configuration", 1416 }, 1417 "ma-schedule-timing": { 1418 "ma-timing-name": "startup plus up to one hour", 1419 "ma-timing-startup": { 1420 }, 1421 "ma-timing-random-spread": "3600000" 1422 } 1423 } 1424 ], 1425 "ma-credentials": { } 1426 } 1427 } 1429 Given the pre-configuration information the MA is able to contact the 1430 Controller and receive an updated/expanded Configuration. In this 1431 example additional Control Protocol tasks to post Status and 1432 Capabilities to the Controller and fetch the Instruction are added as 1433 well as moving the schedule timing for contacting the Controller to 1434 hourly. 1436 // Configuration 1438 { 1439 "ma-config": { 1440 "ma-agent-id": "550e8400-e29b-41d4-a716-446655440000", 1441 "ma-control-tasks": [ 1442 { 1443 "ma-task-name": "Controller configuration", 1444 "ma-task-registry-entry": 1445 "urn:ietf:lmap:control:http_controller_configuration", 1446 "ma-task-options": [{"name": "channel", 1447 "value": "Controller channel"}] 1448 }, 1449 { 1450 "ma-task-name": "Controller status and capabilities", 1451 "ma-task-registry-entry": 1452 "urn:ietf:lmap:control:http_control_status_and_capabilities", 1453 "ma-task-options": [{"name": "channel", 1454 "value": "Controller channel"}] 1455 }, 1456 { 1457 "ma-task-name": "Controller instruction", 1458 "ma-task-registry-entry": 1459 "urn:ietf:lmap:control:http_controller_instruction", 1460 "ma-task-options": [{"name": "channel", 1461 "value": "Controller channel"}] 1462 } 1463 ], 1464 "ma-control-channels": [ 1465 { 1466 "ma-channel-name": "Controller channel", 1467 "ma-channel-target": "http://www.example.com/lmap/controller", 1468 "ma-channel-credientials": { } 1469 } 1470 ], 1471 "ma-control-schedules": [ 1472 { 1473 "ma-schedule-name": "Controller schedule", 1474 "ma-schedule-tasks": [ 1475 { 1476 "ma-schedule-task-name": "Controller configuration", 1477 }, 1478 { 1479 "ma-schedule-task-name": 1480 "Controller status and capabilities", 1482 }, 1483 { 1484 "ma-schedule-task-name": "Controller instruction", 1485 } 1486 ], 1487 "ma-schedule-timing": { 1488 "ma-timing-name": "hourly randomly", 1489 "ma-timing-calendar": { 1490 "ma-calendar-minutes": ["00"], 1491 "ma-calendar-seconds": ["00"] 1492 }, 1493 "ma-timing-random-spread": "3600000" 1494 } 1495 } 1496 ], 1497 "ma-credentials": { } 1498 } 1499 } 1501 The above configuration now contacts the Controller randomnly within 1502 each hour. The following is an example of the Status and 1503 Capabilities information that is transferred from the MA to the 1504 Controller. 1506 // Status and Capabilities 1508 { 1509 "ma-status-and-capabilities": { 1510 "ma-agent-id": "550e8400-e29b-41d4-a716-446655440000", 1511 "ma-device-id": "urn:dev:mac:0024befffe804ff1", 1512 "ma-hardware": "mfr-home-gateway-v10", 1513 "ma-firmware": "25637748-rev2a", 1514 "ma-version": "ispa-v1.01", 1515 "ma-interfaces": [ 1516 { 1517 "ma-interface-name": "broadband", 1518 "ma-interface-type": "PPPoE" 1519 } 1520 ], 1521 "ma-last-task": "", 1522 "ma-last-report": "", 1523 "ma-last-instruction": "", 1524 "ma-last-configuration": "2014-06-08T22:47:31+00:00", 1525 "ma-supported-tasks": [ 1526 { 1527 "ma-task-name": "Controller configuration", 1528 "ma-task-registry": 1529 "urn:ietf:lmap:control:http_controller_configuration" 1530 },, 1531 { 1532 "ma-task-name": "Controller status and capabilities", 1533 "ma-task-registry": 1534 "urn:ietf:lmap:control:http_control_status_and_capabilities" 1535 }, 1536 { 1537 "ma-task-name": "Controller instruction", 1538 "ma-task-registry": 1539 "urn:ietf:lmap:control:http_controller_instruction" 1540 }, 1541 { 1542 "ma-task-name": "Report", 1543 "ma-task-registry": "urn:ietf:lmap:report:http_report" 1544 }, 1545 { 1546 "ma-task-name": "UDP Latency", 1547 "ma-task-registry": 1548 "urn:ietf:ippm:measurement:UDPLatency-Poisson-XthPercMean" 1549 } 1550 ] 1551 } 1552 } 1554 After fetching the status and capabilties the Controller issues and 1555 Instruction to the MA to perform a single UDP latency measurement 1556 task 4 times a day and to report the results immediately. 1558 // Instruction 1560 { 1561 "ma-instruction": { 1562 "ma-instruction-tasks": [ 1563 { 1564 "ma-task-name": "UDP Latency", 1565 "ma-task-registry-entry": 1566 "urn:ietf:ippm:measurement:UDPLatency-Poisson-XthPercMean", 1567 "ma-task-options": [ 1568 {"name": "X", "value": "99"}, 1569 {"name":"rate", "value": "5"}, 1570 {"name":"duration", "value": "30.000"}, 1571 {"name":"interface", "value": "broadband"}, 1572 {"name":"destination-ip", 1573 "value": {"version":"ipv4", "ip-address":"192.168.2.54"}}, 1574 {"name":"destination-port", "value": "50000"}, 1575 {"name":"source-port", "value": "50000"} 1576 ], 1577 "ma-task-suppress-by-default": "TRUE" 1578 }, 1579 { 1580 "ma-task-name": "Report", 1581 "ma-task-registry-entry": "urn:ietf:lmap:report:http_report", 1582 "ma-task-options": [ 1583 {"name": "report-with-no-data", "value": "FALSE"}, 1584 {"name": "channel", "value": "Collector A"]} 1585 ], 1586 "ma-task-suppress-by-default": "FALSE" 1587 } 1588 ], 1589 "ma-report-channels": [ 1590 { 1591 "ma-channel-name": "Collector A", 1592 "ma-channel-target": "http://www.example2.com/lmap/collector", 1593 "ma-channel-credientials": { } 1594 } 1595 ], 1596 "ma-instruction-schedules": [ 1597 { 1598 "ma-schedule-name": "4 times daily test UDP latency and report", 1599 "ma-schedule-tasks": [ 1600 { 1601 "ma-schedule-task-name": "UDP Latency", 1602 "ma-schedule-destination-tasks": [ 1603 { 1604 "ma-schedule-task-output-selection": [1], 1605 "ma-schedule-task-destination-schedule-name": 1606 "4 times daily test UDP latency and report", 1607 "ma-schedule-task-destination-task-configuration-names": 1608 "Report" 1609 } 1610 ] 1611 }, 1612 { 1613 "ma-schedule-task-name": "Report", 1614 } 1615 ], 1617 "ma-schedule-timing": { 1618 "ma-timing-name": "once every 6 hours", 1619 "ma-timing-calendar": { 1620 "ma-calendar-hours": ["00", "06", "12", "18"], 1621 "ma-calendar-minutes": ["00"], 1622 "ma-calendar-seconds": ["00"] 1623 }, 1624 "ma-timing-random-spread": "21600000" 1625 } 1626 } 1627 ] 1628 } 1629 } 1631 The report task in the Instruction is executed immediately after the 1632 UDP test and transfers the following data to the Collector. 1634 // Report 1636 { 1637 "ma-report": { 1638 "ma-report-date": "2014-06-09T02:30:45+00:00", 1639 "ma-report-agent-id": "550e8400-e29b-41d4-a716-446655440000", 1640 "ma-report-tasks": [ 1641 { 1642 "ma-report-task-name": "UDP Latency", 1643 "ma-report-task-registry-entry": 1644 "urn:ietf:ippm:measurement:UDPLatency-Poisson-XthPercMean", 1645 "ma-report-scheduled-task-options": [ 1646 {"name": "X", "value": "99"}, 1647 {"name":"rate", "value": "5"}, 1648 {"name":"duration", "value": "30.000"}, 1649 {"name":"interface", "value": "broadband"}, 1650 {"name":"destination-ip", 1651 "value": {"version":"ipv4", "ip-address":"192.168.2.54"}}, 1652 {"name":"destination-port", "value": "50000"}, 1653 {"name":"source-port", "value": "50000"} 1654 ], 1655 "ma-report-task-column-labels": 1656 ["start-time", "conflicting-tasks", "cross-traffic", 1657 "mean", "min", "max"], 1658 "ma-report-task-rows": 1659 ["2014-06-09T02:30:10+00:00", "", "0", 1660 "20.13", "18.3", "24.1"] 1661 } 1662 ] 1663 } 1664 } 1666 The Controller decides that there is a problem with the UDP L:atency 1667 test and issues a Suppression Instruction. Since the task is marked 1668 as suppressible by default, simply turning on suppression will stop 1669 the task being executed in future. 1671 // Suppression 1673 { 1674 "ma-instruction": { 1675 "ma-suppression": { 1676 "ma-suppression-enabled": "TRUE" 1677 } 1678 } 1679 } 1681 Authors' Addresses 1683 Trevor Burbridge 1684 BT 1685 Adastral Park, Martlesham Heath 1686 Ipswich IP5 3RE 1687 United Kingdom 1689 Email: trevor.burbridge@bt.com 1691 Philip Eardley 1692 BT 1693 Adastral Park, Martlesham Heath 1694 Ipswich IP5 3RE 1695 United Kingdom 1697 Email: philip.eardley@bt.com 1699 Marcelo Bagnulo 1700 Universidad Carlos III de Madrid 1701 Av. Universidad 30 1702 Leganes, Madrid 28911 1703 Spain 1705 Email: marcelo@it.uc3m.es 1706 Juergen Schoenwaelder 1707 Jacobs University Bremen 1708 Campus Ring 1 1709 Bremen 28759 1710 Germany 1712 Email: j.schoenwaelder@jacobs-university.de