idnits 2.17.1 draft-ietf-lmap-information-model-01.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 35 instances of too long lines in the document, the longest one being 52 characters in excess of 72. == 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 456 has weird spacing: '...ule-obj ma-...' == Line 576 has weird spacing: '...ion-obj ma-su...' == Line 693 has weird spacing: '...ace-obj ma-...' == Line 700 has weird spacing: '...ity-obj ma-s...' == Line 779 has weird spacing: '...ask-obj ma-re...' == (7 more instances...) -- The document date (June 26, 2014) is 3591 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-14) exists of draft-ietf-lmap-framework-03 Summary: 1 error (**), 0 flaws (~~), 9 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Burbridge 3 Internet-Draft P. Eardley 4 Intended status: Standards Track BT 5 Expires: December 28, 2014 M. Bagnulo 6 Universidad Carlos III de Madrid 7 J. Schoenwaelder 8 Jacobs University Bremen 9 June 26, 2014 11 Information Model for Large-Scale Measurement Platforms (LMAP) 12 draft-ietf-lmap-information-model-01 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 December 28, 2014. 47 Copyright Notice 49 Copyright (c) 2014 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (http://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 65 2. Notation . . . . . . . . . . . . . . . . . . . . . . . . . . 4 66 3. LMAP Information Model . . . . . . . . . . . . . . . . . . . 4 67 3.1. Information Structure . . . . . . . . . . . . . . . . . . 4 68 3.2. Pre-Configuration Information . . . . . . . . . . . . . . 8 69 3.3. Configuration Information . . . . . . . . . . . . . . . . 9 70 3.4. Instruction Information . . . . . . . . . . . . . . . . . 10 71 3.5. Logging Information . . . . . . . . . . . . . . . . . . . 13 72 3.6. Capability and Status Information . . . . . . . . . . . . 15 73 3.7. Reporting Information . . . . . . . . . . . . . . . . . . 16 74 3.8. Schedules . . . . . . . . . . . . . . . . . . . . . . . . 18 75 3.9. Channels . . . . . . . . . . . . . . . . . . . . . . . . 20 76 3.10. Task Configurations . . . . . . . . . . . . . . . . . . . 21 77 3.11. Timing Information . . . . . . . . . . . . . . . . . . . 22 78 3.11.1. Periodic Timing . . . . . . . . . . . . . . . . . . 23 79 3.11.2. Calendar Timing . . . . . . . . . . . . . . . . . . 23 80 3.11.3. One-Off Timing . . . . . . . . . . . . . . . . . . . 24 81 3.11.4. Immediate Timing . . . . . . . . . . . . . . . . . . 24 82 3.11.5. Startup Timing . . . . . . . . . . . . . . . . . . . 25 83 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 84 5. Security Considerations . . . . . . . . . . . . . . . . . . . 25 85 6. Appendix: JSON Example . . . . . . . . . . . . . . . . . . . 25 86 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 34 87 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 34 88 8.1. Normative References . . . . . . . . . . . . . . . . . . 34 89 8.2. Informative References . . . . . . . . . . . . . . . . . 34 90 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 34 92 1. Introduction 94 A large-scale measurement platform is a collection of components that 95 work in a coordinated fashion to perform measurements from a large 96 number of vantage points. The main components of a large-scale 97 measurement platform are the Measurement Agents (hereafter MAs), the 98 Controller(s) and the Collector(s). 100 The MAs are the elements actually performing the measurements. The 101 MAs are controlled by exactly one Controller at a time and the 102 Collectors gather the results generated by the MAs. In a nutshell, 103 the normal operation of a large-scale measurement platform starts 104 with the Controller instructing a set of one or more MAs to perform a 105 set of one or more Measurement Tasks at a certain point in time. The 106 MAs execute the instructions from a Controller, and once they have 107 done so, they report the results of the measurements to one or more 108 Collectors. The overall framework for a Large Measurement platform 109 as used in this document is described in detail in 110 [I-D.ietf-lmap-framework]. 112 A large-scale measurement platform involves basically three 113 protocols, namely, a Control protocol between a Controller and the 114 MAs, a Report protocol between the MAs and the Collector(s) and 115 several measurement protocols between the MAs and Measurement Peers 116 (MPs), used to actually perform the measurements. In addition some 117 information is required to be configured on the MA prior to any 118 communication with the initial Controller. 120 This document defines the information model for both the Control and 121 the Report protocol along with pre-configuration information that is 122 required before communicating with the Controller, broadly named as 123 the LMAP Information Model. The measurement protocols are out of the 124 scope of this document. 126 As defined in [RFC3444], the LMAP IM defines the concepts involved in 127 a large-scale measurement platform at a high level of abstraction, 128 independent of any specific implementation or actual protocol used to 129 exchange the information. It is expected that the proposed 130 information model can be used with different protocols in different 131 measurement platform architectures and across different types of MA 132 devices (e.g., home gateway, smartphone, PC, router). 134 The definition of an Information Model serves a number of purposes: 136 1. To guide the standardisation of one or more Control and Report 137 protocol and data model implementations 139 2. To enable high-level inter-operability between different Control 140 and Report protocols by facilitating translation between their 141 respective data models such that a Controller could instruct sub- 142 populations of MAs using different protocols 144 3. To form agreement of what information needs to be held by an MA 145 and passed over the Control and Report interfaces and support the 146 functionality described in the LMAP framework 148 4. Enable existing protocols and data models to be assessed for 149 their suitability as part of a large-scale measurement system 151 2. Notation 153 This document use an object-oriented programming-like notation to 154 define the parameters (names/values) of the objects of the 155 information model. An optional field is enclosed by [ ], and an 156 array is indicated by two numbers in angle brackets, >, where m 157 indicates the minimal number of values, and n is the maximum. The 158 symbol * for n means no upper bound. 160 3. LMAP Information Model 162 3.1. Information Structure 164 The information described herein relates to the information stored, 165 received or transmitted by a Measurement Agent as described within 166 the LMAP framework [I-D.ietf-lmap-framework]. As such, some subsets 167 of this information model are applicable to the measurement 168 Controller, Collector and systems that pre-configure the Measurement 169 Agent. The information described in these models will be transmitted 170 by protocols using interfaces between the Measurement Agent and such 171 systems according to a Data Model. 173 For clarity the information model is divided into six sections: 175 1. Pre-Configuration Information. Information pre-configured on the 176 Measurement Agent prior to any communication with other 177 components of the LMAP architecture (i.e., the Controller, 178 Collector and Measurement Peers), specifically detailing how to 179 communicate with a Controller and whether the device is enabled 180 to participate as an MA. 182 2. Configuration Information. Update of the pre-configuration 183 information during the registration of the MA or subsequent 184 communication with the Controller, along with the configuration 185 of further parameters about the MA (rather than the Tasks it 186 should perform) that were not mandatory for the initial 187 communication between the MA and a Controller. 189 3. Instruction Information. Information that is received by the MA 190 from the Controller pertaining to the Tasks that should be 191 executed. This includes the task execution Schedules (other than 192 the Controller communication Schedule supplied as 193 (pre)configuration information) and related information such as 194 the Task Configuration, communication Channels to Collectors and 195 schedule Timing information. It also inlcudes Task Suppression 196 information that is used to over-ride normal Task execution 197 during emergency situations. 199 4. Logging Information. Information transmitted from the MA to the 200 Controller detailing the results of any configuration operations 201 along with error and status information from the operation of the 202 MA. 204 5. Capability and Status Information. Information on the general 205 status and capabilities of the MA. For example, the set of 206 measurements that are supported on the device. 208 6. Reporting Information. Information transmitted from the MA to 209 the Collector including measurement results and the context in 210 which they were conducted. 212 In addition the MA may hold further information not described herein, 213 and which may be optionally transferred to or from other systems 214 including the Controller and Collector. One example of information 215 in this category is subscriber or line information that may be 216 extracted by a task and reported by the MA in the reporting 217 communication to a Collector. 219 It should also be noted that the MA may be in communication with 220 other management systems which may be responsible for configuring and 221 retrieving information from the MA device. Such systems, where 222 available, can perform an important role in transferring the pre- 223 configuration information to the MA or enabling/disabling the 224 measurement functionality of the MA. 226 The Information Model is divided into sub-sections for a number of 227 reasons. Firstly the grouping of information facilitates reader 228 understanding. Secondly, the particular groupings chosen are 229 expected to map to different protocols or different transmissions 230 within those protocols. 232 The granularity of data transmitted in each operation of the Control 233 and Report Protocols is not dictated by the Information Model. For 234 example, the Instruction object may be delivered in a single 235 operation. Alternatively, Schedules and Task Configurations may be 236 separated or even each Schdule/Task Configuration may be delivered 237 individually. Similarly the Information Model does not dictate 238 whether data is read, write, or read/write. For example, some 239 Control Protocols may have the ability to read back Configuration and 240 Instruction information which have been previosuly set on the MA. 241 Lastly, while some protocols may simply overwrite information (for 242 example refreshing the entire Instruction Information), other 243 protocols may have the ability to update or delete selected items of 244 information. 246 The information in these six sections is captured by a number of 247 common information objects. These objects are also described later 248 in this document and comprise of: 250 1. Schedules. A set of Schedules tell the MA to do something. 251 Without a Schedule no Task (from a measurement to reporting or 252 communicating with the Controller) is ever executed. Schedules 253 are used within the Instruction to specify what tasks should be 254 performed, when, and how to direct their results. A Schedule is 255 also used within the pre-Configuration and Configuration 256 information in order to execute the Task or Tasks required to 257 communicate with the Controller. 259 2. Channels. A set of Channel objects are used to communicate with 260 a number of endpoints (i.e. the Controller and Collectors). Each 261 Channel object contains the information required for the 262 communication with a single endpoint such as the target location 263 and security details. Channels are referenced from within 264 Schedules in order to say how Tasks should communicate. 266 3. Task Configurations. A set of Task Configurations is used to 267 configure the Tasks that are run by the MA. This includes the 268 registry entry for the Task and any configuration parameters. 269 Task Configurations are referenced from a Schedule in order to 270 specify what Tasks the MA should execute. 272 4. Timings. A set of Timing objects that can be referenced from the 273 Schedules. Each Schedule always references exactly one Timing 274 object. A Timing object specfies either a singleton or series of 275 time events. They are used to indicate when Tasks should be 276 executed. 278 The following diagram illustrates the structure in which these common 279 information objects are referenced. The references are achieved by 280 each object (Channel, Task Configuration, Timing) being given a short 281 text name that is used by other objects. The objects shown in 282 brackets are part of the internal object structure of a Schedule. 284 Schedule 285 |----------> Timing 286 |----------> (Scheduled Tasks) 287 |----------> Task Configuration 288 |----------> (Task datasets) 289 |----------> Channels 290 |----------> Ouput Tasks 292 It should be clear that the general capability of an MA is simply to 293 execute Schedules. Every other action of an MA is implemented as a 294 Task. As such, these actions are configured through Task 295 Configurations and executed according to the Timing referenced by the 296 Schedule in which they appear. Tasks can implement a variety of 297 different types of actions. While in terms of the Information Model, 298 all Tasks have the same information, it can help conceptually to 299 think of different Task categories: 301 1. Measurement Tasks 303 A. Active Measurement Tasks implement an active measurement 304 protocol to a remote network host 306 B. Passive Measurement Tasks analyse traffic passing through the 307 MA device or traffic that may be eavesdropped 309 C. Data Capture Tasks capture and analyse passive information 310 stored on the MA device such as counters and device/network 311 status information 313 2. Data Transfer Tasks 315 A. Reporting Tasks report the results or Measurement Tasks to 316 Collectors 318 B. Control Task(s) implement the Control Protocol and 319 communicate with the Controller. Depending on the Control 320 Protocol this may be a number of specialist tasks such as: 321 Configuration Task; Instruction Task; Suppression Task; 322 Capabilities Task; Logging Task etc. 324 3. Data Analysis Tasks can exist to analyse data from other 325 Measurement Tasks locally on the MA 327 4. Data Management Tasks may exist to clean-up, filter or compress 328 data on the MA such as Measurement Task results 330 3.2. Pre-Configuration Information 332 This information is the minimal information that needs to be pre- 333 configured to the MA in order for it to successfully communicate with 334 a Controller during the registration process. The pre-configuration 335 information is a subset of the Configuration Information along with 336 some parameters that are not under the control of the LMAP framework 337 (such as the the device identifier and device security credentials). 339 This pre-configuration information needs to include a URL of the 340 initial Controller where configuration information can be retrieved 341 along with the security information required for the communication 342 including the certificate of the Controller (or the certificate of 343 the Certification Authority which was used to issue the certificate 344 for the Controller). All this is expressed as a Channel. Multiple 345 channels may be given to the Controller (such as over different 346 interfaces or network protocols). 348 Where the MA pulls information from the Controller, the Pre- 349 Configuration Information also needs to contain the timing of the 350 communication with the Controller as well as the nature of the 351 communication itself (such as the protocol and data to be 352 transfered). The timing is given as a Schedule that executes the 353 Task(s) responsible for communication with the Controller. It is 354 this Task (or Tasks) that implement the Control protocol between the 355 MA and the Controller. The Task(s) may take additional parameters in 356 which case a Task Configuration can also be included. 358 Even where information is pushed to the MA from the Controller 359 (rather than pulled by the MA), a Schedule still needs to be 360 supplied. In this case the Schedule will simply execute a Controller 361 listener task when the MA is started. A Channel is still required 362 for the MA to establish secure communication with the Controller. 364 It can be seen that these Channels, Schedules and Task Configurations 365 for the initial MA-Controller communication are no different in terms 366 of the Information Model to any other Channel, Schedule or Task 367 Configuration that might execute a Measurement Task or report the 368 measurement results (as described later). 370 The MA may be pre-configured with an MA ID, or may use a Device ID in 371 the initial Controller contact before it is assigned an MA ID. The 372 Device ID may be a MAC address or some other device identifier 373 expressed as a URN. 375 Detail of the information model elements: 377 // MA pre-configuration minimal information to communicate initially with Controller 379 object { 380 [uuid ma-agent-id;] 381 ma-task-obj ma-control-tasks<0..*>; 382 ma-channel-obj ma-control-channels<1..*>; 383 ma-schedule-obj ma-control-schedules<0..*>; 384 [urn ma-device-id;] 385 credentials ma-credentials; 386 } ma-config-obj; 388 The detail of the Channel and Schedule objects are described later 389 since they are common to several parts of the information model. 391 3.3. Configuration Information 393 During registration or at any later point at which the MA contacts 394 the Controller (or vice-versa), the choice of Controller, details for 395 the timing of communication with the Controller or parameters for the 396 communication Task(s) can be changed (as captured by the Channels, 397 Schedules and Task Configurations objects). For example the pre- 398 configured Controller (specified as a Channel or Channels) may be 399 replaced with a specific Controller that is more appropriate to the 400 MA device type, location or characteristics of the network (e.g. 401 access technology type or broadband product). The initial 402 communication Schedule may be replaced with one more relevant to 403 routine communications between the MA and the Controller. 405 While some Control protocols and uses may only use a single Schedule, 406 other protocols and uses may uses several Schedules (and related data 407 transfer Tasks) to update the Configuration Information, transfer the 408 Instruction Information, transfer Capability and Status Information 409 and send other information to the Controller such as log or error 410 notifications. Multiple Channels may be used to communicate with the 411 Controller over multiple interfaces (e.g. to send logging information 412 over a different network). 414 In addition the MA will be given further items of information that 415 relate specifically to the MA rather than the measurements it is to 416 conduct or how to report results. The assignment of an ID to the MA 417 is mandatory. Optionally a Group ID may also be given which 418 identifies a group of interest to which that MA belongs. For example 419 the group could represent an ISP, broadband product, technology, 420 market classification, geographic region, or a combination of 421 multiple such characteristics. Where the Measurement Group ID is set 422 an additional flag (the Report MA ID flag) is required to control 423 whether the Measurement Agent ID is also to be reported. The 424 reporting of a Group ID without the MA ID allows the MA to remain 425 anonymous, which may be particularly useful to prevent tracking of 426 mobile MA devices. 428 Optionally an MA can also be configured to stopexecuting any 429 Instruction Schedule if the Controller is unreachable. This can be 430 used as a fail-safe to stop Measurement and other Tasks being 431 conducted when there is doubt that the Instruction Information is 432 still valid. This is simply represented as a time window in 433 milliseconds since the last communication with the Controller after 434 which Instruction Schedules are to be suspended. The appropriate 435 vaue of the time window will depend on the specified communication 436 Schedule with the Controller and the duration for which the system is 437 willing to tolerate continued operation with potentially stale 438 Instruction Information. 440 While pre-configuration is persistent upon device reset or power 441 cycle due to its very nature, the persistency of the addtional 442 configuration information may be control protocol dependent. Some 443 protocols may assume that reset devices will revert back to their 444 pre-configuration state, while other protocols may assume that all 445 configuration and instruction information is held in persistent 446 storage. 448 Detail of the additional and updated information model elements: 450 // MA Configuration 452 object { 453 uuid ma-agent-id; 454 [ma-task-obj ma-control-tasks<0..*>;] 455 ma-channel-obj ma-control-channels<1..*>; 456 [mas-schedule-obj ma-control-schedules<0..*>]; 457 [urn ma-device-id;] 458 credentials ma-credentials; 459 [string ma-group-id;] 460 [boolean ma-report-ma-id-flag;] 461 [int ma-control-channel-failure-threshold;] 462 } ma-config-obj; 464 3.4. Instruction Information 466 The Instruction information model has four sub-elements: 468 1. Instruction Task Configurations 470 2. Report Channels 472 3. Instruction Schedules 473 4. Suppression 475 The Instruction supports the exceution of all Tasks on the MA except 476 those that deal with communication with the Controller (specified in 477 (pre)configuration information). The Tasks are configured in 478 Instruction Task Configurations and inlcuded by reference in 479 Instruction Schdules that specify when to execute them. The results 480 are communicated to other Tasks or over Report Channels. Suppression 481 is used to temporarily stop the excution of new Tasks as specified by 482 the Instruction Schedules (and optionaly to stop ongoing Tasks). 484 A Task Configuration is used to configure the optional parameters of 485 a Task. It also serves to instruct the MA about the Task including 486 the ability to resolve the Task to an executable and specifying the 487 schema for the Task parameters. 489 A Report Channel defines how to communicate with a single remote 490 system specified by a URL. A Report Channel is used to send results 491 to single Collector but is no different in terms of the Information 492 Model to the Control Channel used to transfer information between the 493 MA and the Controller. Several Report Channels can be defined to 494 enable results to be split or duplicated across different 495 destinations. A single Channel can also be used by multiple 496 Schedules to transfer data at different cycles to the same Collector. 497 E.g. a single Collector may receive data at three different cycle 498 rates, one Schedule reporting hourly, another reporting daily and a 499 third specifying that results should be sent immediately for on- 500 demand measurement tasks. Alternatively multiple Report Channels can 501 be used to send Measurement Task results to different Collectors. 502 The details of the Channel element is described later as it is common 503 to several objects. 505 Instruction Schedules specify which Tasks to execute according to a 506 simngle given Timing (that can execute a single or repeated series of 507 Tasks). The Schedule also specifies how to deal with Task inputs and 508 outputs - e.g. sending selected outputs to other Tasks or specifying 509 the Report Channels that should be used to report results to 510 Collectors. 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 as indicated by the suppress-by-default flag 539 in the Task Configuration. If tasks or schedules are listed 540 explicitly then these tasks will be suppressed regardless of the 541 suppress-by-default flag. 543 Suppression stops new Tasks from executing. In addtion, the 544 Suppression information also supports an additional Boolean that is 545 used to select whether on-going tasks are also to be terminated. 547 Unsuppression is achieved through either overwriting the Measurement 548 Suppression information (e.g. changing 'enabled' to False) or through 549 the use of an End time such that the Measurement Suppression will no 550 longer be in effect beyond this time. The datetime format used for 551 all elements in the information model (e.g. the suppression start and 552 end dates) MUST conform to RFC 3339 [RFC3339] and ISO8601. 554 The goal when defining these four different elements is to allow each 555 part of the information model to change without affecting the other 556 three elements. For example it is envisaged that the Report Channels 557 and the set of Task Configurations will be relatively static. The 558 Instruction Schedule, on the other hand, is likely to be more 559 dynamic, as the measurement panel and test frequency are changed for 560 various business goals. Another example is that measurements can be 561 suppressed with a Suppression command without removing the existing 562 Instruction Schedules that would continue to apply after the 563 Suppression expires or is removed. In terms of the Controller-MA 564 communication this can reduce the data overhead. It also encourages 565 the re-use of the same standard Task Configurations and Reporting 566 Channels to help ensure consistency and reduce errors. 568 Definition of the information model elements: 570 // Instruction to the MA to configure Tasks, Channels, Schedules and Suppression 572 object { 573 ma-task-obj ma-instruction-tasks<0..*>; 574 ma-channel-obj ma-report-channels<0..*>; 575 ma-schedule-obj ma-instruction-schedules<0..*>; 576 ma-suppression-obj ma-suppression; 577 } ma-instruction-obj; 579 // Suppression object to temporarily override new task execution in Instructions and optionally stop currently running tasks 581 object { 582 boolean ma-suppression-enabled; 583 [boolean ma-suppression-stop-ongoing-tasks;] // default: false 584 [datetime ma-suppression-start;] // default: immediate 585 [datetime ma-suppression-end;] // default: indefinite 586 [string ma-suppression-task-names<0..*>;] 587 // default: all tasks if 588 // ma-suppression-task-names is empty 589 [string ma-suppression-schedule-names<0..*>;] 590 // default: all schedules if 591 // ma-suppression-schedule-names is empty 592 } ma-suppression-obj; 594 3.5. Logging Information 596 The MA may report on the success or failure of Configuration or 597 Instruction communications from the Controller. In addition further 598 operational logs may be produced during the operation of the MA and 599 updates to capabilities may also be reported. Reporting this 600 information is achieved simply and flexibly in exactly the same 601 manner as any other Task. We make no distinction between a 602 Measurement Task conducting an active or passive network measurement 603 and one which solely retrieves static or dynamic information from the 604 MA such as capabilities or logging information. One or more logging 605 tasks can be programmed or configured to capture subsets of the 606 Logging Information. These logging tasks are then executed by 607 Schedules which also specify that the resultant data is to be 608 transferred over the Controller Channels. 610 The type of Logging Information will fall into three different 611 categories: 613 1. Success/failure/warning messages in response to information 614 updates from the Controller. Failure messages could be produced 615 due to some inability to receive or parse the Controller 616 communication, or if the MA is not able to act as instructed. 617 For example: 619 * "Measurement Schedules updated OK" 621 * "Unable to parse JSON" 623 * "Missing mandatory element: Measurement Timing" 625 * "'Start' does not conform to schema - expected datetime" 627 * "Date specified is in the past" 629 * "'Hour' must be in the range 1..24" 631 * "Schedule A refers to non-existent Measurement Task 632 Configuration" 634 * "Measurement Task Configuration X registry entry Y not found" 636 * "Updated Measurement Task Configurations do not include M used 637 by Measurement Schedule N" 639 2. Operational updates from the MA. For example: 641 * "Out of memory: cannot record result" 643 * "Collector 'collector.example.com' not responding" 645 * "Unexpected restart" 647 * "Suppression timeout" 649 * "Failed to execute Measurement Task Configuration H" 651 3. Status updates from the MA. For example: 653 * "Interface added: eth3 " 655 * "Supported measurements updated" 657 * "New IP address on eth0: xxx.xxx.xxx.xxx" 659 This Information Model document does not detail the precise format of 660 logging information since it is to a large extent protocol and MA 661 specific. However, some common information can be identified. 663 MA Logging information model elements: 665 // Logging object 667 object { 668 uuid ma-log-agent-id; 669 datetime ma-log-event-time; 670 code ma-log-code; 671 string ma-log-description; 672 } ma-log-obj; 674 3.6. Capability and Status Information 676 The MA will hold Capability Information that can be retrieved by a 677 Controller. Capabilities include the interface details available to 678 Measurement Tasks and Channels as well as the set of Measurement 679 Tasks that are actually installed or available on the MA. Status 680 information includes the times that operations were last performed 681 such as contacting the Controller or producing Reports. 683 MA Status information model elements: 685 // Main MA Status information object 687 object { 688 uuid ma-agent-id; 689 urn ma-device-id; 690 string ma-hardware; 691 string ma-firmware; 692 string ma-version; 693 ma-interface-obj ma-interfaces<0..*>; 695 datetime ma-last-measurement; 696 datetime ma-last-report; 697 datetime ma-last-instruction; 698 datetime ma-last-configuration; 700 ma-task-capability-obj ma-supported-tasks<0..*>; 701 } ma-status-obj; 702 // Interface information 704 object { 705 string ma-interface-name; 706 string ma-interface-type; 707 [int ma-interface-speed;] // mbps 708 [string ma-link-layer-address;] 709 [ip-address ma-interface-ip-addresses<0..*>]; 710 [ip-address ma-interface-gateways<0..*>;] 711 [ip-address ma-interface-dns-servers<0..*>;] 712 } ma-interface-obj; 714 // Supported tasks 716 object { 717 string ma-task-name; 718 uri ma-task-registry; 719 } ma-task-capability-obj; 721 3.7. Reporting Information 723 At a point in time specified by a Schedule, the MA will execute a 724 task or tasks that communicate a set of measurement results to the 725 Collector. Some of these Tasks (notably Reporting Tasks) will 726 understand how to transmit task results over a specified Report 727 Channel to a Collector. 729 It should be noted that the output from Tasks does not need to be 730 sent to communication Channels. It can alternatively, or 731 additionally, be sent to other Tasks on the MA. This facilitates 732 using a first Measurement Task to control the operation of a later 733 Measurement Task (such as first probing available line speed and then 734 adjusting the operation of a video testing measurement) and also to 735 allow local processing of data to output alarms (e.g. when 736 performance drops from earlier levels). Of course, subsequent Tasks 737 also include Tasks that implement the reporting protocol(s) and 738 transfer data to one or more Collector(s). 740 The report is structured hierarchically to avoid repetition of report 741 header and Measurement Task Configuration information. The report 742 starts with the timestamp of the report generation on the MA and 743 details about the MA including the optional Measurement Agent ID and 744 Group ID (controlled by the Configuration Information). 746 No context information, such as line speed or broadband product are 747 included within the report header information as this data is 748 reported by individual tasks at the time they execute. Either a 749 Measurement Task can report contextual parameters that are relevant 750 to that particular measurement, or specific tasks can be used to 751 gather a set of contextual and environmental data. at certain times 752 independent of the reporting schedule. 754 After the report header information the results are reported grouped 755 according to different Measurement Task Configurations. Each Task 756 section starts with replicating the Measurement Task Configuration 757 information before the result headers (titles for data columns) and 758 the result data rows. The result data rows may optionally include an 759 indication of the cross-traffic. Cross traffic is defined as the 760 total number of Bytes both upstream and downstream of non-measurement 761 traffic passing through the interfaces used by a Measurement Task 762 during the measurement period. 764 Where the Configuration and Instruction information represent 765 information transmitted via the Control Protocol, the Report 766 represents the information that is transmitted via the Report 767 Protocol. It is constructed at the time of sending a report and 768 represents the inherent structure of the information that is sent to 769 the Collector. 771 Information model elements: 773 // Main Report object with report header information 775 object { 776 datetime ma-report-date; 777 [uuid ma-report-agent-id;] 778 [string ma-report-group-id;] 779 ma-report-task-obj ma-report-tasks<0..*>; 780 } ma-report-obj; 782 // Report task header information 784 object { 785 ma-task-obj ma-report-task-config; 786 string ma-report-task-column-labels<0..*>; 787 ma-result-row-obj ma-report-task-rows<0..*>; 788 } ma-report-task-obj; 790 // Report tasks result rows 792 object { 793 datetime ma-report-result-time; 794 string ma-report-conflicting-tasks<0..*>; 795 [int ma-report-result-cross-traffic;] // Bytes of non-measurement traffic 796 // on measurement interface during measurement period 797 data ma-report-result-values<0..*>; 798 } ma-result-row-obj; 800 The ma-context-obj, which covers things like line speed or the device 801 type, is not further detailed here. 803 3.8. Schedules 805 A Schedule specifies the execution of a single or repeated series of 806 Tasks. Each Schedule contains basically two elements: a list of 807 Tasks to be executed and a timing object for the Schedule. The 808 Schedule basically states what Tasks to run (with what 809 configuration), how to report the results, and when to run the Tasks. 811 Multiple Tasks in the list of a single Measurement Schedule will be 812 executed in order with minimal gaps. Tasks in different Schedules 813 can execute in parallel with such conflicts beings reported in the 814 Reporting Information. 816 As well as specifying which Tasks to execute, the Schedule also 817 specifies where to send the data outputs from each Task. Specifying 818 this within the Schedule allows the highest level of flexibility 819 since it is even possible to send the output from different 820 executions of the same Task to different destinations. Since a 821 single Task may have multiple outputs, the Schedule can independently 822 specify which outputs go to which destinations. For example, a 823 Measurement Task might report routine results to a data Reporting 824 Task that communicates hourly via the Broadband PPP interface, but 825 also outputs emergency conditions via an alarm Reporting Task 826 communicating immediately over a GPRS channel. 828 The destination options for a Task are either another Task or a 829 Channel. In this way the output of a Task can be sent to another 830 Task. For example a Measurement Task may send its output to a data 831 transfer Task that reports the batched data to a Collector at a later 832 time. Alternatively the output from a Measurement Task may be fed to 833 an alarm processing task that monitors the results of a series of 834 Measurement Tasks. Some Tasks will also understand how to send/ 835 receive data to/from Channels using the Reporting/Control protocol. 836 Since Channels are bi-directional they can be considered inputs as 837 well as outputs to the Control and Reporting Tasks that utlilise 838 them. Any Task that does not implement either the Reporting or 839 Control protocol will ignore any specified Channels (e.g. A 840 Measurement Task will not know how to report results to a Collector 841 using the Report Protocol. Instead results can be passed to a 842 Reporting Task that has the apropriate Collector specified as a 843 Channel). 845 The tasks outputs and channels are controlled using a series of 846 filters. Each filter is an array of integers specifying which Task 847 datasets should be mapped to which output tasks and/or channels. 849 Example: A Schedule references a single Measurement Task 850 Configuration for the UDP latency. It specifies that results are 851 to be sent to a Reporting Task. This Reporting Task is executed 852 by a separate Schedule that specifies that it should run hourly at 853 5 minutes past the hour. When run this Reporting Task takes the 854 data generated by the UDP latency Task as well as any other data 855 to be included in the hourly report and transfers it to the 856 Collector over the Report Channel specified within its own 857 Schedule. 859 // main Schedule object with Timing and list of Scheduled Tasks 861 object { 862 string ma-schedule-name; 863 ma-sched-task-obj ma-schedule-tasks<0..*>; 864 ma-timing-obj ma-schedule-timing; 865 } ma-schedule-obj; 867 // Scheduled Task object with reference (by name string) to Task Configuration and input/output mapping 868 // of task datasets to output tasks and channels 870 object { 871 string ma-schedule-task-name; 872 ma-sched-dataset-obj ma-schedule-task-datasets<0..*>; 873 } ma-sched-task-obj; 875 // Selected Task interfaces (filtered by Integer list) can be output to other Task Configurations 876 // (referenced by name string) or connected to input/output Channels (referenced by name string) 878 object { 879 [int ma-schedule-task-filters<0..*>;] // default: all 880 [string ma-schedule-task-output-task-names<0..*>]; 881 [string ma-schedule-task-channel-names<0..*>]; 882 } ma-sched-dataset-obj; 883 3.9. Channels 885 A Channel defines a bi-directional communication channel between the 886 MA and a Controller or Collector. Multiple Channels can be defined 887 to enable results to be split or duplicated across different 888 Collectors. 890 Each Channel contains the details of the endpoint (including location 891 and security credential information such as the certificate). The 892 timing of when to communicate over a Channel is specified within the 893 Schedule. The certificate can be the digital certificate associated 894 to the FQDN in the URL or it can be the certificate of the 895 Certification Authority that was used to issue the certificate for 896 the FQDN (Fully Qualified Domain Name) of the target URL (which will 897 be retrieved later on using a communication protocol such as TLS). 898 In order to establish a secure channel, the MA will use it's own 899 security credentials (in the Configuration Information) and the given 900 credentials for the individual Channel end-point. 902 As with theTask Configurations, each Channel is also given a local 903 short name by which it can be referenced from a Schedule. 905 Although the same in terms of information, Channels used for 906 communication with the Controller are refered to as Control Channels 907 whereas Channels to Collectors are refered to as Report Channels. 908 Hence Control Channels will be referenced from within the Control 909 Schedule, whereas Report Channels will be referenced from within the 910 Instruction Schedule. 912 Multiple interfaces are also supported. For example the Controller 913 could choose to receive some results over GPRS. This is especially 914 useful when such results indicate the loss of connectivity on a 915 different network interface. 917 Example: A Channel using for reporting results may specify that 918 results are to be sent to the URL (https://collector.foo.org/ 919 report/), using the appropriate digital certificate to establish a 920 secure channel.. 922 // Channel object with name string allowing reference from Schedule. Contains channel endpoint target URL and security 923 // credentials to establish secure channel. Optionally allows interface specification (by interface name string reference) 924 // and connection when no data is pending for transfer 926 object { 927 string ma-channel-name; 928 url ma-channel-target; 929 credentials ma-channel-credentials; 930 [string ma-channel-interface-name;] 931 } ma-channel-obj; 933 3.10. Task Configurations 935 Conceptually each Task Configuration defines the parameters of a Task 936 that the Measurement Agent (MA) may perform at some point in time. 937 It does not by itself actually instruct the MA to perform them at any 938 particular time (this is done by a Schedule). Tasks can be 939 Measurement Tasks (i.e. those Tasks actually performing some type of 940 passive or active measurement) or any other scheduled activity 941 performed by the MA such as transferring information to or from the 942 Controller and Collectors. Other examples of Tasks may include data 943 manipulation or processing Tasks conducted on the MA. 945 A Measurement Task Configuration is the same in information terms to 946 any other Task Configuration. Both measurement and non-measurement 947 Tasks have a registry entry to enable the MA to uniquely identify the 948 Task it should execute and retrieve the schema for any parameters 949 that may be passed to the Task. This registry entry is specified as 950 a URI and can therefore identify the Task within a namespace or point 951 to a web or local file location for the Task information. As 952 mentioned previously this entry may refer to the Measurement Task in 953 a public namespace [I-D.bagnulo-ippm-new-registry] that is used to 954 define the Measurement Task. 956 Example: A Measurement Task Configuration may configure a single 957 Measurement Task for measuring UDP latency. The Measurement Task 958 Configuration could define the destination port and address for 959 the measurement as well as the duration, internal packet timing 960 strategy and other parameters (for example a stream for one hour 961 and sending one packet every 500 ms). It may also define the 962 output type and possible parameters (for example the output type 963 can be the 95th percentile mean) where the measurement task 964 accepts such parameters. It does NOT define when the task starts 965 (this is defined by the Schedule element), so it does not by 966 itself instruct the MA to actually perform this Measurement Task. 968 The Task Configuration will include a local short name for reference 969 by a Schedule. Task Configurations will also contain a registry 970 entry as described above. In addition the Task can be configured 971 through a set of configuration Options. The nature and number of 972 these Options will depend upon the Task and will be resolved through 973 the registry parameter. 975 A parameter that may be present for Reporting Tasks is whether to 976 report if there is no measurement result data pending to be 977 transferred to the Collector. 979 The Task Configuration also contains a suppress-by-default flag that 980 specifies the behaviour of a default suppress instruction (that does 981 not list explicit tasks or schedules). If this flag is set to FALSE 982 then the Task will not be suppressed. It should be noted that 983 Controller Tasks are not subject to the suppression instruction and 984 therefore this flag will be ignored in such cases. 986 In addition the Task Configuration may optionally also be given a 987 Measurement Cycle ID. The purpose of this ID is to easily identify a 988 set of measurement results that have been produced by Measurement 989 Tasks with comparable Options. This ID could be manually incremented 990 or otherwise changed when an Option change is implemented which could 991 mean that two sets of results should not be directly compared. 993 // Task Configuration object with string name to allow reference from Schedule. Contains URI to link to registry or local 994 // specification of Task. Options allow the configuration of Task parameters (in the form of name-value pairs) 996 object { 997 string ma-task-name; 998 uri ma-task-registry; 999 name-value-pair ma-task-options<0..*>; 1000 [boolean ma-task-suppress-by-default;] // default: TRUE 1001 [string ma-task-cycle-id;] 1002 } ma-task-obj; 1004 3.11. Timing Information 1006 The Timing information object used throughout the information models 1007 can take one of five different forms: 1009 1. Periodic. Specifies a start, end and interval time in 1010 milliseconds 1012 2. Calendar: Specifies a calendar based pattern - e.g. 22 minutes 1013 past each hour of the day on weekdays 1015 3. One Off: A single instance occurring at a specific time 1017 4. Immediate: Should occur as soon as possible 1018 5. Startup: Should occur whenever the MA is started (e.g. at device 1019 startup) 1021 Optionally each of the options may also specify a randomness that 1022 should be evaluated and applied separately to each indicated event. 1024 The datetime format used for all elements in the information model 1025 MUST conform to RFC 3339 [RFC3339] and ISO8601. 1027 // Main Timing object with name string to allow reference by Schedule 1028 // Must be specialised by one of the Timing options. 1029 // Includes optional uniform random spread in ms from start time given by Timing specialisation 1031 object { 1032 [string ma-timing-name;] 1033 union { 1034 ma-periodic-obj ma-timing-periodic; 1035 ma-calendar-obj ma-timing-calendar; 1036 ma-one-off-obj ma-timing-one-off; 1037 ma-immediate-obj ma-timing-immediate; 1038 ma-startup-obj ma-timing-startup; 1039 } 1040 [int ma-timing-random-spread;] // milliseconds 1041 } ma-timing-obj; 1043 3.11.1. Periodic Timing 1045 Information model elements: 1047 // Timing specialisation to run a series of Tasks repeated at set intervals 1049 object { 1050 [datetime ma-periodic start;] // default: immediate 1051 [datetime ma-periodic-end;] // default: indefinite 1052 int ma-periodic-interval; // milliseconds 1053 } ma-periodic-obj; 1055 3.11.2. Calendar Timing 1057 Calendar Timing supports the routine execution of Measurement Tasks 1058 at specific times and/or on specific dates. It can support more 1059 flexible timing than Periodic Timing since the Measurement Task 1060 execution does not have to be uniformly spaced. For example a 1061 Calendar Timing could support the execution of a Measurement Task 1062 every hour between 6pm and midnight on weekdays only. 1064 Calendar Timing is also required to perform measurements at 1065 meaningful instances in relation to network usage (e.g., at peak 1066 times). If the optional timezone offset is not supplied then local 1067 system time is assumed. This is essential in some use cases to 1068 ensure consistent peak-time measurements as well as supporting MA 1069 devices that may be in an unknown timezone or roam between different 1070 timezones (but know their own timezone information such as through 1071 the mobile network). 1073 Information model elements: 1075 // Timing specialisation to run repeated Tasks at specific times and/or days 1077 object { 1078 [datetime ma-calendar-start;] // default: immediate 1079 [datetime ma-calendar-end;] // default: indefinite 1080 [int ma-calendar-months<0..*>;] // default: 1-12 1081 [days ma-calendar-days-of-week<0..*>;] // default: all 1082 [int ma-calendar-hours<0..*>;] // default: 0-23 1083 [int ma-calendar-minutes<0..*>;] // default: 0-59 1084 [int ma-calendar-seconds<0..*>;] // default: 0-59 1085 [int ma-calendar-timezone-offset;] 1086 // default: system timezone offset 1087 } ma-calendar-obj; 1089 3.11.3. One-Off Timing 1091 Information model elements: 1093 // Timing specialisation to run once at a specified time/date 1095 object { 1096 datetime ma-one-off-time; 1097 } ma-one-off-obj; 1099 3.11.4. Immediate Timing 1101 The immediate timing object has no further information elements. The 1102 measurement or report is simply to be done as soon as possible. 1104 // Timing specialisation to run immediately 1106 object { 1107 // empty 1108 } ma-immediate-obj; 1110 3.11.5. Startup Timing 1112 The immediate timing object has no further information elements. The 1113 measurement or report is simply done at MA initiation. 1115 // Timing specialisation to run at MA startup 1117 object { 1118 // empty 1119 } ma-startup-obj; 1121 4. IANA Considerations 1123 This document makes no request of IANA. 1125 Note to RFC Editor: this section may be removed on publication as an 1126 RFC. 1128 5. Security Considerations 1130 This Information Model deals with information about the control and 1131 reporting of the Measurement Agent. There are broadly two security 1132 considerations for such an Information Model. Firstly the 1133 Information Model has to be sufficient to establish secure 1134 communication channels to the Controller and Collector such that 1135 other information can be sent and received securely. Additionally, 1136 any mechanisms that the Network Operator or other device 1137 administrator employs to pre-configure the MA must also be secure to 1138 protect unauthorized parties from modifying pre-configuration 1139 information. The second consideration is that no mandated 1140 information items should pose a risk to confidentiality or privacy 1141 given such secure communication channels. For this latter reason 1142 items such as the MA context and MA ID are left optional and can be 1143 excluded from some deployments. This would, for example, allow the 1144 MA to remain anonymous and for information about location or other 1145 context that might be used to identify or track the MA to be omitted 1146 or blurred. 1148 6. Appendix: JSON Example 1150 In order to give an example of data in the Information Model we need 1151 to select a data model language. In this example we have expressed 1152 the Data Model using JSON as this will be of direct interest to some 1153 Control and Report Protocols. The example is broken down into a 1154 number of different steps that might adhere to the steps within a 1155 Control and Report Protocol: 1157 1. Pre-configuration. 1159 2. Configuration 1161 3. Capabilities 1163 4. Instruction 1165 5. Report 1167 6. Suppression 1169 While the pre-configuration is not delivered as part of the Control 1170 Protocol, the same JSON data model is used for consistency and to aid 1171 the reader. 1173 // Pre-Configuration 1175 { 1176 "ma-config": { 1177 "ma-agent-id": "550e8400-e29b-41d4-a716-446655440000", 1178 "ma-control-tasks": [ 1179 { 1180 "ma-task-name": "Controller configuration", 1181 "uri": "urn:ietf:lmap:control:http_controller_configuration" 1182 } 1183 ] 1184 "ma-control-channels": [ 1185 { 1186 "ma-channel-name": "Controller channel", 1187 "ma-channel-target": "http://www.example.com/lmap/controller", 1188 "ma-channel-credientials": { } // structure of certificate ommitted for brevity 1189 } 1190 ] 1191 "ma-control-schedules": [ 1192 { 1193 "ma-schedule-name": "pre-configured schedule", 1194 "ma-schedule-tasks": { 1195 { 1196 "ma-schedule-task-name": "Controller configuration", 1197 "ma-schedule-task-datasets": [ 1198 { 1199 "ma-schedule-task-channel-names": "Controller channel" 1200 } 1201 ] 1202 } 1203 } 1204 "ma-schedule-timing": { 1205 "ma-timing-name": "startup plus up to one hour", 1206 "ma-timing-startup": { 1207 } 1208 "ma-timing-random-spread": "3600000" 1209 } 1210 } 1211 ] 1212 "ma-credentials": { } // structure of certificate ommitted for brevity 1213 } 1214 } 1216 Given the pre-configuration information the MA is able to contact the 1217 Controller and receive an updated/expanded Configuration. In this 1218 example additional Control Protocol tasks to post Status and 1219 Capabilities to the Controller and fetch the Instruction are added as 1220 well as moving the schedule timing for contacting the Controller to 1221 hourly. 1223 // Configuration 1225 { 1226 "ma-config": { 1227 "ma-agent-id": "550e8400-e29b-41d4-a716-446655440000", 1228 "ma-control-tasks": [ 1229 { 1230 "ma-task-name": "Controller configuration", 1231 "uri": "urn:ietf:lmap:control:http_controller_configuration" 1232 }, 1233 { 1234 "ma-task-name": "Controller status and capabilities", 1235 "uri": "urn:ietf:lmap:control:http_controller_status_and_capabilities" 1236 }, 1237 { 1238 "ma-task-name": "Controller instruction", 1239 "uri": "urn:ietf:lmap:control:http_controller_instruction" 1240 } 1241 ] 1242 "ma-control-channels": [ 1243 { 1244 "ma-channel-name": "Controller instruction", 1245 "ma-channel-target": "http://www.example.com/lmap/controller", 1246 "ma-channel-credientials": { } // structure of certificate ommitted for brevity 1247 } 1248 ] 1249 "ma-control-schedules": [ 1250 { 1251 "ma-schedule-name": "Controller schedule", 1252 "ma-schedule-tasks": { 1253 { 1254 "ma-schedule-task-name": "Controller configuration", 1255 "ma-schedule-task-datasets": [ 1256 { 1257 "ma-schedule-task-channel-names": ["Controller channel"] 1258 } 1259 ] 1260 }, 1261 { 1262 "ma-schedule-task-name": "Controller status and capabilities", 1263 "ma-schedule-task-datasets": [ 1264 { 1265 "ma-schedule-task-channel-names": ["Controller channel"] 1266 } 1268 ] 1269 }, 1270 { 1271 "ma-schedule-task-name": "Controller instruction", 1272 "ma-schedule-task-datasets": [ 1273 { 1274 "ma-schedule-task-channel-names": ["Controller channel"] 1275 } 1276 ] 1277 } 1278 } 1279 "ma-schedule-timing": { 1280 "ma-timing-name": "hourly randomly", 1281 "ma-timing-calendar": { 1282 "ma-calendar-minutes": ["00"], 1283 "ma-calendar-seconds": ["00"] 1284 } 1285 "ma-timing-random-spread": "3600000" 1286 } 1287 } 1288 ] 1289 "ma-credentials": { } // structure of certificate ommitted for brevity 1290 } 1291 } 1293 The above configuration now contacts the Controller randomnly within 1294 each hour. The following is an example of the Status and 1295 Capabilities information that is transferred from the MA to the 1296 Controller. 1298 // Status and Capabilities 1300 { 1301 ma-status-and-capabilities { 1302 "ma-agent-id": "550e8400-e29b-41d4-a716-446655440000", 1303 "ma-device-id": "urn:dev:mac:0024befffe804ff1" 1304 "ma-hardware": "mfr-home-gateway-v10" 1305 "ma-firmware": "25637748-rev2a" 1306 "ma-version": "ispa-v1.01" 1307 "ma-interfaces: [ 1308 { 1309 "ma-interface-name": "broadband", 1310 "ma-interface-type": "PPPoE" 1311 } 1312 ] 1313 "ma-last-measurement: "", 1314 "ma-last-report: "", 1315 "ma-last-instruction: "", 1316 "ma-last-configuration: "2014-06-08T22:47:31+00:00", 1317 "ma-supported-tasks: [ 1318 { 1319 "ma-task-name": "Controller configuration", 1320 "ma-task-registry": "urn:ietf:lmap:control:http_controller_configuration" 1321 }, 1322 { 1323 "ma-task-name": "Controller status and capabilities", 1324 "ma-task-registry": "urn:ietf:lmap:control:http_controller_status_and_capabilities" 1325 }, 1326 { 1327 "ma-task-name": "Controller instruction", 1328 "ma-task-registry": "urn:ietf:lmap:control:http_controller_instruction" 1329 }, 1330 { 1331 "ma-task-name": "Report", 1332 "ma-task-registry": "urn:ietf:lmap:report:http_report" 1333 }, 1334 { 1335 "ma-task-name": "UDP Latency", 1336 "ma-task-registry": "urn:ietf:ippm:measurement:UDPLatency-Poisson-XthPercentileMean" 1337 } 1338 ] 1339 } 1340 } 1341 After fetching the status and capabilties the Controller issues and 1342 Instruction to the MA to perform a single UDP latency measurement 1343 task 4 times a day and to report the results immediately. 1345 // Instruction 1347 { 1348 "ma-instruction": { 1349 "ma-instruction-tasks": [ 1350 { 1351 "ma-task-name": "UDP Latency", 1352 "uri": "urn:ietf:ippm:measurement:UDPLatency-Poisson-XthPercentileMean", 1353 "ma-task-options": [ 1354 {"name": "X", "value": "99"}, 1355 {"name":"rate", "value": "5"}, 1356 {"name":"duration", "value": "30.000"}, 1357 {"name":"interface", "value": "broadband"}, 1358 {"name":"destination-ip", "value": {"version":"ipv4", "ip-address":"192.168.2.54"}}, 1359 {"name":"destination-port", "value": "50000"}, 1360 {"name":"source-port", "value": "50000"} 1361 ], 1362 "ma-task-suppress-by-default": "TRUE" 1363 }, 1364 { 1365 "ma-task-name": "Report", 1366 "uri": "urn:ietf:lmap:report:http_report", 1367 "ma-task-options": [ 1368 {"name": "report-with-no-data", "value": "FALSE"} 1369 ], 1370 "ma-task-suppress-by-default": "FALSE" 1371 } 1372 ] 1373 "ma-report-channels": [ 1374 { 1375 "ma-channel-name": "Collector A", 1376 "ma-channel-target": "http://www.example2.com/lmap/collector", 1377 "ma-channel-credientials": { } // structure of certificate ommitted for brevity 1378 } 1379 ] 1380 "ma-instruction-schedules": [ 1381 { 1382 "ma-schedule-name": "4 times daily test UDP latency and report", 1383 "ma-schedule-tasks": { 1384 { 1385 "ma-schedule-task-name": "UDP Latency", 1386 "ma-schedule-task-datasets": [ 1387 { 1388 "ma-schedule-task-output-task-names": "Report" 1390 } 1391 ] 1392 }, 1393 { 1394 "ma-schedule-task-name": "Report", 1395 "ma-schedule-task-datasets": [ 1396 { 1397 "ma-schedule-task-channel-names": "Collector A" 1398 } 1399 ] 1400 } 1401 } 1402 "ma-schedule-timing": { 1403 "ma-timing-name": "once every 6 hours", 1404 "ma-timing-calendar": { 1405 "ma-calendar-hours": ["00", "06", "12", "18"], 1406 "ma-calendar-minutes": ["00"], 1407 "ma-calendar-seconds": ["00"] 1408 } 1409 "ma-timing-random-spread": "21600000" 1410 } 1411 } 1412 ] 1413 } 1414 } 1416 The report task in the Instruction is executed immediately after the 1417 UDP test and transfers the following data to the Collector. 1419 // Report 1421 { 1422 ma-report: { 1423 "ma-report-date": "2014-06-09T02:30:45+00:00", 1424 "ma-report-agent-id": "550e8400-e29b-41d4-a716-446655440000", 1425 "ma-report-tasks": [ 1426 "ma-report-task-config": { 1427 "ma-task-name": "UDP Latency", 1428 "uri": "urn:ietf:ippm:measurement:UDPLatency-Poisson-XthPercentileMean", 1429 "ma-task-options": [ 1430 {"name": "X", "value": "99"}, 1431 {"name":"rate", "value": "5"}, 1432 {"name":"duration", "value": "30.000"}, 1433 {"name":"interface", "value": "broadband"}, 1434 {"name":"destination-ip", "value": {"version":"ipv4", "ip-address":"192.168.2.54"}}, 1435 {"name":"destination-port", "value": "50000"}, 1436 {"name":"source-port", "value": "50000"} 1437 ] 1438 }, 1439 "ma-report-task-column-labels": ["time", "conflicting-tasks", "cross-traffic", "mean"], 1440 "ma-report-task-rows": [ 1441 {"2014-06-09T02:30:10+00:00", "", "0", "20.13"} 1442 ] 1443 ] 1444 } 1445 } 1447 The Controller decides that there is a problem with the UDP L:atency 1448 test and issues a Suppression Instruction. Since the task is marked 1449 as suppressable by default, simply turning on suppression will stop 1450 the task being executed in future. 1452 // Suppression 1454 { 1455 "ma-instruction": { 1456 "ma-suppression": { 1457 "ma-suppression-enabled": "TRUE" 1458 { 1459 } 1460 } 1462 7. Acknowledgements 1464 The notation was inspired by the notation used in the ALTO protocol 1465 specification. 1467 Philip Eardley, Trevor Burbridge, Marcelo Bagnulo and Juergen 1468 Schoenwaelder work in part on the Leone research project, which 1469 receives funding from the European Union Seventh Framework Programme 1470 [FP7/2007-2013] under grant agreement number 317647. 1472 8. References 1474 8.1. Normative References 1476 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1477 Requirement Levels", BCP 14, RFC 2119, March 1997. 1479 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 1480 Internet: Timestamps", RFC 3339, July 2002. 1482 8.2. Informative References 1484 [I-D.bagnulo-ippm-new-registry] 1485 Bagnulo, M., Burbridge, T., Crawford, S., Eardley, P., and 1486 A. Morton, "A registry for commonly used metrics", draft- 1487 bagnulo-ippm-new-registry-01 (work in progress), July 1488 2013. 1490 [I-D.ietf-lmap-framework] 1491 Eardley, P., Morton, A., Bagnulo, M., Burbridge, T., 1492 Aitken, P., and A. Akhter, "A framework for large-scale 1493 measurement platforms (LMAP)", draft-ietf-lmap- 1494 framework-03 (work in progress), January 2014. 1496 [RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between 1497 Information Models and Data Models", RFC 3444, January 1498 2003. 1500 Authors' Addresses 1502 Trevor Burbridge 1503 BT 1504 Adastral Park, Martlesham Heath 1505 Ipswich IP5 3RE 1506 United Kingdom 1508 Email: trevor.burbridge@bt.com 1509 Philip Eardley 1510 BT 1511 Adastral Park, Martlesham Heath 1512 Ipswich IP5 3RE 1513 United Kingdom 1515 Email: philip.eardley@bt.com 1517 Marcelo Bagnulo 1518 Universidad Carlos III de Madrid 1519 Av. Universidad 30 1520 Leganes, Madrid 28911 1521 Spain 1523 Email: marcelo@it.uc3m.es 1525 Juergen Schoenwaelder 1526 Jacobs University Bremen 1527 Campus Ring 1 1528 Bremen 28759 1529 Germany 1531 Email: j.schoenwaelder@jacobs-university.de