idnits 2.17.1 draft-ietf-lmap-information-model-02.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 50 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 463 has weird spacing: '...ule-obj ma-...' == Line 586 has weird spacing: '...ion-obj ma-su...' == Line 703 has weird spacing: '...ace-obj ma-...' == Line 710 has weird spacing: '...ion-obj ma-...' == Line 712 has weird spacing: '...ity-obj ma-s...' == (8 more instances...) -- The document date (August 20, 2014) is 3529 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 1474 -- Looks like a reference, but probably isn't: '2' on line 927 == Outdated reference: A later version (-14) exists of draft-ietf-lmap-framework-03 Summary: 1 error (**), 0 flaws (~~), 9 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Burbridge 3 Internet-Draft P. Eardley 4 Intended status: Standards Track BT 5 Expires: February 21, 2015 M. Bagnulo 6 Universidad Carlos III de Madrid 7 J. Schoenwaelder 8 Jacobs University Bremen 9 August 20, 2014 11 Information Model for Large-Scale Measurement Platforms (LMAP) 12 draft-ietf-lmap-information-model-02 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 February 21, 2015. 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 . . . . . . . . . . . . . . . . . 11 71 3.5. Logging Information . . . . . . . . . . . . . . . . . . . 13 72 3.6. Capability and Status Information . . . . . . . . . . . . 15 73 3.7. Reporting Information . . . . . . . . . . . . . . . . . . 17 74 3.8. Schedules . . . . . . . . . . . . . . . . . . . . . . . . 18 75 3.9. Channels . . . . . . . . . . . . . . . . . . . . . . . . 21 76 3.10. Task Configurations . . . . . . . . . . . . . . . . . . . 22 77 3.11. Timing Information . . . . . . . . . . . . . . . . . . . 23 78 3.11.1. Periodic Timing . . . . . . . . . . . . . . . . . . 24 79 3.11.2. Calendar Timing . . . . . . . . . . . . . . . . . . 25 80 3.11.3. One-Off Timing . . . . . . . . . . . . . . . . . . . 26 81 3.11.4. Immediate Timing . . . . . . . . . . . . . . . . . . 26 82 3.11.5. Startup Timing . . . . . . . . . . . . . . . . . . . 26 83 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 84 5. Security Considerations . . . . . . . . . . . . . . . . . . . 26 85 6. Appendix: JSON Example . . . . . . . . . . . . . . . . . . . 27 86 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 35 87 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 35 88 8.1. Normative References . . . . . . . . . . . . . . . . . . 35 89 8.2. Informative References . . . . . . . . . . . . . . . . . 35 90 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 35 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 one or more Collectors including measurement results and the 210 context in 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 parenthesis are part of the internal object structure of a Schedule. 284 Schedule 285 |----------> Timing 286 |----------> (Scheduled Tasks) 287 |----------> Task Configuration 288 |----------> (Task Channels and downstream Tasks) 289 |----------> Channels 290 |----------> Downstream Tasks 292 It should be clear that the top-level bahaviour of an MA is simply to 293 execute Schedules. Every action referenced by a Schedule is defined 294 as a 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 structure, it can help conceptually to think 299 of different Task categories: 301 1. Measurement Tasks 303 A. Measurement Tasks measure some aspect of network performance 304 or traffic 306 B. Data Capture Tasks capture and analyse passive information 307 stored on the MA device such as counters and device/network 308 status information 310 2. Data Transfer Tasks 312 A. Reporting Tasks report the results or Measurement Tasks to 313 Collectors 315 B. Control Task(s) implement the Control Protocol and 316 communicate with the Controller. Depending on the Control 317 Protocol this may be a number of specialist tasks such as: 318 Configuration Task; Instruction Task; Suppression Task; 319 Capabilities Task; Logging Task etc. 321 3. Data Analysis Tasks can exist to analyse data from other 322 Measurement Tasks locally on the MA 324 4. Data Management Tasks may exist to clean-up, filter or compress 325 data on the MA such as Measurement Task results 327 3.2. Pre-Configuration Information 329 This information is the minimal information that needs to be pre- 330 configured to the MA in order for it to successfully communicate with 331 a Controller during the registration process. The pre-configuration 332 information is a subset of the Configuration Information along with 333 some parameters that are not under the control of the LMAP framework 334 (such as the the device identifier and device security credentials). 336 This pre-configuration information needs to include a URL of the 337 initial Controller where configuration information can be retrieved 338 along with the security information required for the communication 339 including the certificate of the Controller (or the certificate of 340 the Certification Authority which was used to issue the certificate 341 for the Controller). All this is expressed as a Channel. While 342 multiple Channels may be provided in the pre-configuration 343 information they must all be associated with a single Controller 344 (e.g. over different interfaces or network protocols). 346 Where the MA pulls information from the Controller, the Pre- 347 Configuration Information also needs to contain the timing of the 348 communication with the Controller as well as the nature of the 349 communication itself (such as the protocol and data to be 350 transfered). The timing is given as a Schedule that executes the 351 Task(s) responsible for communication with the Controller. It is 352 this Task (or Tasks) that implement the Control protocol between the 353 MA and the Controller. The Task(s) may take additional parameters in 354 which case a Task Configuration can also be included. 356 Even where information is pushed to the MA from the Controller 357 (rather than pulled by the MA), a Schedule still needs to be 358 supplied. In this case the Schedule will simply execute a Controller 359 listener task when the MA is started. A Channel is still required 360 for the MA to establish secure communication with the Controller. 362 It can be seen that these Channels, Schedules and Task Configurations 363 for the initial MA-Controller communication are no different in terms 364 of the Information Model to any other Channel, Schedule or Task 365 Configuration that might execute a Measurement Task or report the 366 measurement results (as described later). 368 The MA may be pre-configured with an MA ID, or may use a Device ID in 369 the initial Controller contact before it is assigned an MA ID. The 370 Device ID may be a MAC address or some other device identifier 371 expressed as a URN. If the MA ID is not provided at this stage then 372 it must be provided by the Controller during Configuration. 374 Detail of the information model elements: 376 // MA pre-configuration minimal information to communicate initially with Controller 378 object { 379 [uuid ma-agent-id;] 380 ma-task-obj ma-control-tasks<1..*>; 381 ma-channel-obj ma-control-channels<1..*>; 382 ma-schedule-obj ma-control-schedules<1..*>; 383 [urn ma-device-id;] 384 credentials ma-credentials; 385 } ma-config-obj; 387 The detail of the Channel and Schedule objects are described later 388 since they are common to several parts of the information model. 390 3.3. Configuration Information 392 During registration or at any later point at which the MA contacts 393 the Controller (or vice-versa), the choice of Controller, details for 394 the timing of communication with the Controller or parameters for the 395 communication Task(s) can be changed (as captured by the Channels, 396 Schedules and Task Configurations objects). For example the pre- 397 configured Controller (specified as a Channel or Channels) may be 398 replaced with a specific Controller that is more appropriate to the 399 MA device type, location or characteristics of the network (e.g. 400 access technology type or broadband product). The initial 401 communication Schedule may be replaced with one more relevant to 402 routine communications between the MA and the Controller. 404 While some Control protocols and uses may only use a single Schedule, 405 other protocols and uses may uses several Schedules (and related data 406 transfer Tasks) to update the Configuration Information, transfer the 407 Instruction Information, transfer Capability and Status Information 408 and send other information to the Controller such as log or error 409 notifications. Multiple Channels may be used to communicate with the 410 same Controller over multiple interfaces (e.g. to send logging 411 information over a different network). 413 In addition the MA will be given further items of information that 414 relate specifically to the MA rather than the measurements it is to 415 conduct or how to report results. The assignment of an ID to the MA 416 is mandatory. If the MA Agent ID was not optionally provided during 417 the pre-configuration then one must be provided by the Controller 418 during Configuration. Optionally a Group ID may also be given which 419 identifies a group of interest to which that MA belongs. For example 420 the group could represent an ISP, broadband product, technology, 421 market classification, geographic region, or a combination of 422 multiple such characteristics. Where the Measurement Group ID is set 423 an additional flag (the Report MA ID flag) is required to control 424 whether the Measurement Agent ID is also to be reported. The 425 reporting of a Group ID without the MA ID allows the MA to remain 426 anonymous, which may be particularly useful to prevent tracking of 427 mobile MA devices. 429 Optionally an MA can also be configured to stop executing any 430 Instruction Schedule if the Controller is unreachable. This can be 431 used as a fail-safe to stop Measurement and other Tasks being 432 conducted when there is doubt that the Instruction Information is 433 still valid. This is simply represented as a time window in 434 milliseconds since the last communication with the Controller after 435 which Instruction Schedules are to be suspended. The appropriate 436 vaue of the time window will depend on the specified communication 437 Schedule with the Controller and the duration for which the system is 438 willing to tolerate continued operation with potentially stale 439 Instruction Information. 441 While pre-configuration is persistent upon device reset or power 442 cycle due to its very nature, the persistency of the addtional 443 configuration information may be control protocol dependent. Some 444 protocols may assume that reset devices will revert back to their 445 pre-configuration state, while other protocols may assume that all 446 configuration and instruction information is held in persistent 447 storage. 449 It should be noted that control shedules and tasks cannot be 450 suppressed as evidenced by the lack of suppression information in the 451 Configuration. The control schedule must only reference tasks listed 452 as control tasks. Any suppress-by-default flag against control tasks 453 will be ignored. 455 Detail of the additional and updated information model elements: 457 // MA Configuration 459 object { 460 uuid ma-agent-id; 461 [ma-task-obj ma-control-tasks<0..*>;] 462 ma-channel-obj ma-control-channels<1..*>; 463 [ma-schedule-obj ma-control-schedules<0..*>]; 464 [urn ma-device-id;] 465 credentials ma-credentials; 466 [string ma-group-id;] 467 [boolean ma-report-ma-id-flag;] 468 [int ma-control-channel-failure-threshold;] 469 } ma-config-obj; 471 3.4. Instruction Information 473 The Instruction information model has four sub-elements: 475 1. Instruction Task Configurations 477 2. Report Channels 479 3. Instruction Schedules 481 4. Suppression 483 The Instruction supports the exceution of all Tasks on the MA except 484 those that deal with communication with the Controller (specified in 485 (pre)configuration information). The Tasks are configured in 486 Instruction Task Configurations and inlcuded by reference in 487 Instruction Schdules that specify when to execute them. The results 488 are communicated to other Tasks or over Report Channels. Suppression 489 is used to temporarily stop the excution of new Tasks as specified by 490 the Instruction Schedules (and optionaly to stop ongoing Tasks). 492 A Task Configuration is used to configure the optional parameters of 493 a Task. It also serves to instruct the MA about the Task including 494 the ability to resolve the Task to an executable and specifying the 495 schema for the Task parameters. 497 A Report Channel defines how to communicate with a single remote 498 system specified by a URL. A Report Channel is used to send results 499 to single Collector but is no different in terms of the Information 500 Model to the Control Channel used to transfer information between the 501 MA and the Controller. Several Report Channels can be defined to 502 enable results to be split or duplicated across different 503 destinations. A single Channel can also be used by multiple 504 Schedules to transfer data at different cycles to the same Collector. 505 E.g. a single Collector may receive data at three different cycle 506 rates, one Schedule reporting hourly, another reporting daily and a 507 third specifying that results should be sent immediately for on- 508 demand measurement tasks. Alternatively multiple Report Channels can 509 be used to send Measurement Task results to different Collectors. 510 The details of the Channel element is described later as it is common 511 to several objects. 513 Instruction Schedules specify which Tasks to execute according to a 514 given Timing (that can execute a single or repeated series of Tasks). 515 The Schedule also specifies how to deal with Task inputs and outputs 516 - e.g. sending selected outputs to other Tasks or specifying the 517 Report Channels that should be used to report results to Collectors. 519 Measurement Suppression information is used to over-ride the 520 Instruction Schedule and temporarily stop measurements or other Tasks 521 from running on the MA for a defined or indefinite period. While 522 conceptually measurements can be stopped by simply removing them from 523 the Measurement Schedule, splitting out separate information on 524 Measurement Suppression allows this information to be updated on the 525 MA on a different timing cycle or protocol implementation to the 526 Measurement Schedule. It is also considered that it will be easier 527 for a human operator to implement a temporary explicit suppression 528 rather than having to move to a reduced Schedule and then roll-back 529 at a later time. 531 The explicit Suppression instruction message is able to simply 532 enable/disable all Instruction Tasks (that are enabled for default 533 suppression) as well as having fine control on which Tasks are 534 suppressed. Suppression of both specified Task Configurations and 535 Measurement Schedules is supported. Support for disabling specific 536 Task Configurations allows malfunctioning or mis-configured Tasks or 537 Task Configurations that have an impact on a particular part of the 538 network infrastructure (e.g., a particular Measurement Peer) to be 539 targetted. Support for disabling specific Schedules allows for 540 particularly heavy cycles or sets of less essential Measurement Tasks 541 to be suppressed quickly and effectively. Note that Suppression has 542 no effect on either Controller Tasks or Controller Schedules. 544 When no tasks or schedules are explicitly listed, all Instruction 545 tasks will be suppressed (or not) as indicated by the suppress-by- 546 default flag in the Task Configuration. If tasks or schedules are 547 listed explicitly then only these listed tasks or schedules will be 548 suppressed regardless of the suppress-by-default flag. If both 549 individual tasks and individual schedules are listed then the union 550 of these options is considered - i.e. the listed shcedules plus the 551 listed tasks where present in other schedules. 553 Suppression stops new Tasks from executing. In addtion, the 554 Suppression information also supports an additional Boolean that is 555 used to select whether on-going tasks are also to be terminated. 557 Unsuppression is achieved through either overwriting the Measurement 558 Suppression information (e.g. changing 'enabled' to False) or through 559 the use of an End time such that the Measurement Suppression will no 560 longer be in effect beyond this time. The datetime format used for 561 all elements in the information model (e.g. the suppression start and 562 end dates) MUST conform to RFC 3339 [RFC3339] and ISO8601. 564 The goal when defining these four different elements is to allow each 565 part of the information model to change without affecting the other 566 three elements. For example it is envisaged that the Report Channels 567 and the set of Task Configurations will be relatively static. The 568 Instruction Schedule, on the other hand, is likely to be more 569 dynamic, as the measurement panel and test frequency are changed for 570 various business goals. Another example is that measurements can be 571 suppressed with a Suppression command without removing the existing 572 Instruction Schedules that would continue to apply after the 573 Suppression expires or is removed. In terms of the Controller-MA 574 communication this can reduce the data overhead. It also encourages 575 the re-use of the same standard Task Configurations and Reporting 576 Channels to help ensure consistency and reduce errors. 578 Definition of the information model elements: 580 // Instruction to the MA to configure Tasks, Channels, Schedules and Suppression 582 object { 583 ma-task-obj ma-instruction-tasks<0..*>; 584 ma-channel-obj ma-report-channels<0..*>; 585 ma-schedule-obj ma-instruction-schedules<0..*>; 586 ma-suppression-obj ma-suppression; 587 } ma-instruction-obj; 589 // Suppression object to temporarily override new task execution in Instructions and optionally stop currently running tasks 591 object { 592 boolean ma-suppression-enabled; 593 [boolean ma-suppression-stop-ongoing-tasks;] // 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.5. 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 simply and flexibly in exactly the same 611 manner as any other Task. We make no distinction between a 612 Measurement Task conducting an active or passive network measurement 613 and one which solely retrieves static or dynamic information from the 614 MA such as capabilities or logging information. One or more logging 615 tasks can be programmed or configured to capture subsets of the 616 Logging Information. These logging tasks are then executed by 617 Schedules which also specify that the resultant data is to be 618 transferred over 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 * "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.6. Capability and Status Information 686 The MA will hold Capability Information that can be retrieved by a 687 Controller. Capabilities include the interface details available to 688 Measurement Tasks and Channels as well as the set of Measurement 689 Tasks/Roles that are actually installed or available on the MA. 690 Status information includes the times that operations were last 691 performed such as contacting the Controller or producing Reports. 693 MA Status information model elements: 695 // Main MA Status information object 697 object { 698 uuid ma-agent-id; 699 urn ma-device-id; 700 string ma-hardware; 701 string ma-firmware; 702 string ma-version; 703 ma-interface-obj ma-interfaces<0..*>; 705 datetime ma-last-measurement; 706 datetime ma-last-report; 707 datetime ma-last-instruction; 708 datetime ma-last-configuration; 710 [ma-condition-obj ma-conditions<0..*>;] 712 ma-task-capability-obj ma-supported-tasks<0..*>; 713 } ma-status-obj; 715 // Additional status conditions 717 object { 718 string ma-condition-code; 719 string ma-condition-text; 720 } ma-condition-obj 722 // Interface information 724 object { 725 string ma-interface-name; 726 string ma-interface-type; 727 [int ma-interface-speed;] // bps 728 [string ma-link-layer-address;] 729 [ip-address ma-interface-ip-addresses<0..*>]; 730 [ip-address ma-interface-gateways<0..*>;] 731 [ip-address ma-interface-dns-servers<0..*>;] 732 } ma-interface-obj; 734 // Supported tasks/roles 736 object { 737 string ma-task-name; 738 uri ma-task-registry; 739 string ma-task-role; 740 } ma-task-capability-obj; 742 3.7. Reporting Information 744 At a point in time specified by a Schedule, the MA will execute a 745 task or tasks that communicate a set of measurement results to the 746 Collector. Some of these Tasks (notably Reporting Tasks) will 747 understand how to transmit task results over a specified Report 748 Channel to a Collector. Where to send the data is defined within the 749 Schedule information. 751 It should be noted that the output from Tasks does not need to be 752 sent to communication Channels. It can alternatively, or 753 additionally, be sent to other Tasks on the MA. This facilitates 754 using a first Measurement Task to control the operation of a later 755 Measurement Task (such as first probing available line speed and then 756 adjusting the operation of a video testing measurement) and also to 757 allow local processing of data to output alarms (e.g. when 758 performance drops from earlier levels). Of course, subsequent Tasks 759 also include Tasks that implement the reporting protocol(s) and 760 transfer data to one or more Collector(s). 762 The report is structured hierarchically to avoid repetition of report 763 header and Measurement Task Configuration information. The report 764 starts with the timestamp of the report generation on the MA and 765 details about the MA including the optional Measurement Agent ID and 766 Group ID (controlled by the Configuration Information). 768 No context information, such as line speed or broadband product are 769 included within the report header information as this data is 770 reported by individual tasks at the time they execute. Either a 771 Measurement Task can report contextual parameters that are relevant 772 to that particular measurement, or specific tasks can be used to 773 gather a set of contextual and environmental data. at certain times 774 independent of the reporting schedule. 776 After the report header information the results are reported grouped 777 according to different Measurement Task Configurations. Each Task 778 section starts with replicating the Measurement Task Configuration 779 information before the result headers (titles for data columns) and 780 the result data rows. 782 The result row data inlcudes a time for the start of the measurement 783 and optionally an end time where the duration also needs to be 784 considered in the data analysis. The result data rows may optionally 785 include an indication of the cross-traffic. Cross traffic is defined 786 as the total number of Bytes both upstream and downstream of non- 787 measurement traffic passing through the interfaces used by a 788 Measurement Task during the measurement period. The specific 789 Measurement Task may also output other environmental measures in 790 addtion to cross-traffic such as CPU utlisation or interface speed. 791 The encoding of this information will vary dependent upon the data 792 model chosen for the Report Protocol. 794 Where the Configuration and Instruction information represent 795 information transmitted via the Control Protocol, the Report 796 represents the information that is transmitted via the Report 797 Protocol. It is constructed at the time of sending a report and 798 represents the inherent structure of the information that is sent to 799 the Collector. 801 Information model elements: 803 // Main Report object with report header information 805 object { 806 datetime ma-report-date; 807 [uuid ma-report-agent-id;] 808 [string ma-report-group-id;] 809 ma-report-task-obj ma-report-tasks<0..*>; 810 } ma-report-obj; 812 // Report task header information 814 object { 815 ma-task-obj ma-report-task-config; 816 string ma-report-task-column-labels<0..*>; 817 ma-result-row-obj ma-report-task-rows<0..*>; 818 } ma-report-task-obj; 820 // Report tasks result rows 822 object { 823 datetime ma-report-result-start-time; 824 [datetime ma-report-result-end-time;] 825 string ma-report-result-conflicting-tasks<0..*>; 826 [int ma-report-result-cross-traffic;] // Bytes of non-measurement traffic 827 // on measurement interface during measurement period 828 data ma-report-result-values<0..*>; 829 } ma-result-row-obj; 831 3.8. Schedules 833 A Schedule specifies the execution of a single or repeated series of 834 Tasks. Each Schedule contains basically two elements: a list of 835 Tasks to be executed and a timing object for the Schedule. The 836 Schedule states what Tasks to run (with what configuration), how to 837 report the results, and when to run the Tasks. 839 Multiple Tasks in the list of a single Measurement Schedule will be 840 executed in order with minimal gaps. Tasks in different Schedules 841 can execute in parallel with such conflicts beings reported in the 842 Reporting Information. 844 As well as specifying which Tasks to execute, the Schedule also 845 specifies where to send the data outputs from each Task. Specifying 846 this within the Schedule allows the highest level of flexibility 847 since it is even possible to send the output from different 848 executions of the same Task to different destinations. Since a 849 single Task may have multiple outputs, the Schedule can independently 850 specify which outputs go to which destinations. For example, a 851 Measurement Task might report routine results to a data Reporting 852 Task that communicates hourly via the Broadband PPP interface, but 853 also outputs emergency conditions via an alarm Reporting Task 854 communicating immediately over a GPRS channel. 856 The interface options for a Task are either another downstream Task 857 or a Channel. The output of a Task can be sent to another Task. For 858 example a Measurement Task may send its output to a data transfer 859 Task that reports the batched data to a Collector at a later time. 860 Alternatively the output from a Measurement Task may be fed to an 861 alarm processing task that monitors the results of a series of 862 Measurement Tasks. 864 Only some Tasks will understand how to send/receive data to/from 865 Channels using the Reporting/Control protocol. Any Task that does 866 not implement either the Reporting or Control protocol will not have 867 any channel interfaces to configure. Instead results should be 868 passed to a Reporting Task that has the appropriate Collector 869 specified as a Channel. 871 When a task is referenced by a schedule there will be a simultaneous 872 definition of which (if any) channels to use and which (if any) other 873 downstream tasks to send data to. Note that task-to-task data 874 transfer is always specified in association with the scheduled 875 execution of the sending task - there is no need for a corresponding 876 input specification for the receiving task. 878 Example: A Schedule references a single Measurement Task 879 Configuration for the UDP latency. It specifies that results are 880 to be sent to a Reporting Task. This Reporting Task is executed 881 by a separate Schedule that specifies that it should run hourly at 882 5 minutes past the hour. When run this Reporting Task takes the 883 data generated by the UDP latency Task as well as any other data 884 to be included in the hourly report and transfers it to the 885 Collector over the Report Channel specified within its own 886 Schedule. 888 // main Schedule object with Timing and list of Scheduled Tasks 890 object { 891 string ma-schedule-name; 892 ma-sched-task-obj ma-schedule-tasks<0..*>; 893 ma-timing-obj ma-schedule-timing; 894 } ma-schedule-obj; 896 // Scheduled Task object with reference (by name string) to Task Configuration to execute and mapping 897 // to channels and onward tasks 899 object { 900 string ma-schedule-task-name; 901 [ma-sched-channels-obj ma-schedule-channels<0..*>;] 902 [ma-sched-downstream-tasks-obj ma-schedule-downstream-tasks<0..*>;] 903 } ma-sched-task-obj; 905 // Selected Task channel interfaces (selected by integer from array defined by the task) can be connected to 906 // Channels (referenced by name string(s)) 908 object { 909 [int ma-schedule-channel-interface-selection<0..*>;] // default: all 910 [string ma-schedule-channel-names<0..*>]; 911 } ma-sched-channels-obj; 913 // Selected Task outputs to onward tasks (selected by integer from an output array defined by the task) can be sent to 914 // Task Configurations (referenced by name string(s)) 916 object { 917 [int ma-schedule-task-output-selection<0..*>;] // default: all 918 [string ma-schedule-task-downstream-task-configuration-names<0..*>]; 919 } ma-sched-downstream-tasks-obj; 921 Example: A measurement task has two defined inter-task outputs, one 922 for routine measurement results and one for errors during the task 923 execution. These are defined as available outputs by the task and 924 are denoted by the integers 1 & 2. In this example, both outputs 925 are sent to the same reporting task called "Hourly reporting 926 Task". This is done by creating a ma-sched-send-to-tasks-obj with 927 the output selection as [1,2] and the downstream task 928 configuration names as ["Hourly Reporting Task"]. 930 Measurement Task 931 Output 1 -------------+--------------> "Hourly Reporting Task" 932 Output 2 ------------/ 934 3.9. Channels 936 A Channel defines a bi-directional communication channel between the 937 MA and a Controller or Collector. Multiple Channels can be defined 938 to enable results to be split or duplicated across different 939 Collectors. 941 Each Channel contains the details of the remote endpoint (including 942 location and security credential information such as the 943 certificate). The timing of when to communicate over a Channel is 944 specified within the Schedule. The certificate can be the digital 945 certificate associated to the FQDN in the URL or it can be the 946 certificate of the Certification Authority that was used to issue the 947 certificate for the FQDN (Fully Qualified Domain Name) of the target 948 URL (which will be retrieved later on using a communication protocol 949 such as TLS). In order to establish a secure channel, the MA will 950 use it's own security credentials (in the Configuration Information) 951 and the given credentials for the individual Channel end-point. 953 As with theTask Configurations, each Channel is also given a local 954 short name by which it can be referenced from a Schedule. 956 Although the same in terms of information, Channels used for 957 communication with the Controller are refered to as Control Channels 958 whereas Channels to Collectors are refered to as Report Channels. 959 Hence Control Channels will be referenced from within the Control 960 Schedule, whereas Report Channels will be referenced from within the 961 Instruction Schedule. 963 Multiple interfaces are also supported. For example the Controller 964 could choose to receive some results over GPRS. This is especially 965 useful when such results indicate the loss of connectivity on a 966 different network interface. 968 Example: A Channel using for reporting results may specify that 969 results are to be sent to the URL (https://collector.foo.org/ 970 report/), using the appropriate digital certificate to establish a 971 secure channel.. 973 // Channel object with name string allowing reference from Schedule. Contains channel endpoint target URL and security 974 // credentials to establish secure channel. Optionally allows interface specification (by interface name string reference) 975 // and connection when no data is pending for transfer 977 object { 978 string ma-channel-name; 979 url ma-channel-target; 980 credentials ma-channel-credentials; 981 [string ma-channel-interface-name;] 982 } ma-channel-obj; 984 3.10. Task Configurations 986 Conceptually each Task Configuration defines the parameters of a Task 987 that the Measurement Agent (MA) may perform at some point in time. 988 It does not by itself actually instruct the MA to perform them at any 989 particular time (this is done by a Schedule). Tasks can be 990 Measurement Tasks (i.e. those Tasks actually performing some type of 991 passive or active measurement) or any other scheduled activity 992 performed by the MA such as transferring information to or from the 993 Controller and Collectors. Other examples of Tasks may include data 994 manipulation or processing Tasks conducted on the MA. 996 A Measurement Task Configuration is the same in information terms to 997 any other Task Configuration. Both measurement and non-measurement 998 Tasks have a registry entry and specified role to enable the MA to 999 uniquely identify the Task it should execute and retrieve the schema 1000 for any parameters that may be passed to the Task. This registry 1001 entry is specified as a URI and can therefore bye used to identify 1002 the Task within a namespace or point to a web or local file location 1003 for the Task information. As mentioned previously this entry may be 1004 used to identify the Measurement Task in a public namespace 1005 [I-D.bagnulo-ippm-new-registry] . 1007 Example: A Measurement Task Configuration may configure a single 1008 Measurement Task for measuring UDP latency. The Measurement Task 1009 Configuration could define the destination port and address for 1010 the measurement as well as the duration, internal packet timing 1011 strategy and other parameters (for example a stream for one hour 1012 and sending one packet every 500 ms). It may also define the 1013 output type and possible parameters (for example the output type 1014 can be the 95th percentile mean) where the measurement task 1015 accepts such parameters. It does NOT define when the task starts 1016 (this is defined by the Schedule element), so it does not by 1017 itself instruct the MA to actually perform this Measurement Task. 1019 The Task Configuration will include a local short name for reference 1020 by a Schedule. Task Configurations will also contain a registry 1021 entry as described above. In addition the Task can be configured 1022 through a set of configuration Options. The nature and number of 1023 these Options will depend upon the Task and will be resolved through 1024 the registry parameter. These options are expressed as name-value 1025 pairs although the 'value' may be a structured object instead of a 1026 simple string or numeric value. The implementation of these name- 1027 value pairs will vary between data models such as JSON, XML or TR- 1028 069. 1030 A parameter that may be present for Reporting Tasks is whether to 1031 report if there is no measurement result data pending to be 1032 transferred to the Collector. In addtion many tasks will also take 1033 as a parameter which interface to operate over. 1035 The Task Configuration also contains a suppress-by-default flag that 1036 specifies the behaviour of a default suppress instruction (that does 1037 not list explicit tasks or schedules). If this flag is set to FALSE 1038 then the Task will not be suppressed. It should be noted that 1039 Controller Tasks are not subject to the suppression instruction and 1040 therefore this flag will be ignored in such cases. 1042 In addition the Task Configuration may optionally also be given a 1043 Measurement Cycle ID. The purpose of this ID is to easily identify a 1044 set of measurement results that have been produced by Measurement 1045 Tasks with comparable Options. This ID could be manually incremented 1046 or otherwise changed when an Option change is implemented which could 1047 mean that two sets of results should not be directly compared. 1049 // Task Configuration object with string name to allow reference from Schedule. Contains URI to link to registry or local 1050 // specification of the Task. 1051 // Options allow the configuration of Task parameters (in the form of name-value pairs) 1053 object { 1054 string ma-task-name; 1055 uri ma-task-registry-entry; 1056 string ma-role; 1057 name-value-pair ma-task-options<0..*>; 1058 [boolean ma-task-suppress-by-default;] // default: TRUE 1059 [string ma-task-cycle-id;] 1060 } ma-task-obj; 1062 3.11. Timing Information 1064 The Timing information object used throughout the information models 1065 can take one of five different forms: 1067 1. Periodic. Specifies a start, end and interval time in 1068 milliseconds 1070 2. Calendar: Specifies a calendar based pattern - e.g. 22 minutes 1071 past each hour of the day on weekdays 1073 3. One Off: A single instance occurring at a specific time 1075 4. Immediate: Should occur as soon as possible 1077 5. Startup: Should occur whenever the MA is started (e.g. at device 1078 startup) 1080 Optionally each of the options may also specify a randomness that 1081 should be evaluated and applied separately to each indicated event. 1082 This randomness parameter defines a uniform interval in milliseconds 1083 over which the start of the task is delayed from the starting times 1084 specified by the timing object. 1086 Both the Periodic and Calendar timing objects allow for a series of 1087 tasks to be executed. While both have an optional end time, it is 1088 best practice to always configure an end time and refresh the 1089 information periodically to ensure that lost MAs do not continue 1090 their tasks forever. 1092 The datetime format used for all elements in the information model 1093 MUST conform to RFC 3339 [RFC3339] and ISO8601. 1095 // Main Timing object with name string to allow reference by Schedule 1096 // Must be specialised by one of the Timing options. 1097 // Includes optional uniform random spread in ms from start time given by Timing specialisation 1099 object { 1100 [string ma-timing-name;] 1101 union { 1102 ma-periodic-obj ma-timing-periodic; 1103 ma-calendar-obj ma-timing-calendar; 1104 ma-one-off-obj ma-timing-one-off; 1105 ma-immediate-obj ma-timing-immediate; 1106 ma-startup-obj ma-timing-startup; 1107 } 1108 [int ma-timing-random-spread;] // milliseconds 1109 } ma-timing-obj; 1111 3.11.1. Periodic Timing 1113 Information model elements: 1115 // Timing specialisation to run a series of Tasks repeated at set intervals 1117 object { 1118 [datetime ma-periodic start;] // default: immediate 1119 [datetime ma-periodic-end;] // default: indefinite 1120 int ma-periodic-interval; // milliseconds 1121 } ma-periodic-obj; 1123 3.11.2. Calendar Timing 1125 Calendar Timing supports the routine execution of Measurement Tasks 1126 at specific times and/or on specific dates. It can support more 1127 flexible timing than Periodic Timing since the Measurement Task 1128 execution does not have to be uniformly spaced. For example a 1129 Calendar Timing could support the execution of a Measurement Task 1130 every hour between 6pm and midnight on weekdays only. 1132 Calendar Timing is also required to perform measurements at 1133 meaningful instances in relation to network usage (e.g., at peak 1134 times). If the optional timezone offset is not supplied then local 1135 system time is assumed. This is essential in some use cases to 1136 ensure consistent peak-time measurements as well as supporting MA 1137 devices that may be in an unknown timezone or roam between different 1138 timezones (but know their own timezone information such as through 1139 the mobile network). 1141 Days of week are define using three character strings "Mon", "Tue", 1142 "Wed", "Thu", "Fri", "Sat", "Sun". 1144 If a day of the month is specified that does not exist in the month 1145 (e.g. 29 in Feburary) then those values are ignored. 1147 Information model elements: 1149 // Timing specialisation to run repeated Tasks at specific times and/or days 1151 object { 1152 [datetime ma-calendar-start;] // default: immediate 1153 [datetime ma-calendar-end;] // default: indefinite 1154 [int ma-calendar-months<0..*>;] // default: 1-12 1155 [days ma-calendar-days-of-week<0..*>;] // default: all 1156 [int ma-calendar-days-of-month<0..*>;] // default 1-31 1157 [int ma-calendar-hours<0..*>;] // default: 0-23 1158 [int ma-calendar-minutes<0..*>;] // default: 0-59 1159 [int ma-calendar-seconds<0..*>;] // default: 0-59 1160 [int ma-calendar-timezone-offset;] 1161 // default: system timezone offset 1162 } ma-calendar-obj; 1163 3.11.3. One-Off Timing 1165 Information model elements: 1167 // Timing specialisation to run once at a specified time/date 1169 object { 1170 datetime ma-one-off-time; 1171 } ma-one-off-obj; 1173 3.11.4. Immediate Timing 1175 The immediate timing object has no further information elements. The 1176 measurement or report is simply to be done as soon as possible. 1178 // Timing specialisation to run immediately 1180 object { 1181 // empty 1182 } ma-immediate-obj; 1184 3.11.5. Startup Timing 1186 The immediate timing object has no further information elements. The 1187 measurement or report is simply done at MA initiation. 1189 // Timing specialisation to run at MA startup 1191 object { 1192 // empty 1193 } ma-startup-obj; 1195 4. IANA Considerations 1197 This document makes no request of IANA. 1199 Note to RFC Editor: this section may be removed on publication as an 1200 RFC. 1202 5. Security Considerations 1204 This Information Model deals with information about the control and 1205 reporting of the Measurement Agent. There are broadly two security 1206 considerations for such an Information Model. Firstly the 1207 Information Model has to be sufficient to establish secure 1208 communication channels to the Controller and Collector such that 1209 other information can be sent and received securely. Additionally, 1210 any mechanisms that the Network Operator or other device 1211 administrator employs to pre-configure the MA must also be secure to 1212 protect unauthorized parties from modifying pre-configuration 1213 information. The second consideration is that no mandated 1214 information items should pose a risk to confidentiality or privacy 1215 given such secure communication channels. For this latter reason 1216 items such as the MA context and MA ID are left optional and can be 1217 excluded from some deployments. This would, for example, allow the 1218 MA to remain anonymous and for information about location or other 1219 context that might be used to identify or track the MA to be omitted 1220 or blurred. 1222 6. Appendix: JSON Example 1224 In order to give an example of data in the Information Model we need 1225 to select a data model language. In this example we have expressed 1226 the Data Model using JSON as this will be of direct interest to some 1227 Control and Report Protocols. The example is broken down into a 1228 number of different steps that might adhere to the steps within a 1229 Control and Report Protocol: 1231 1. Pre-configuration. 1233 2. Configuration 1235 3. Capabilities 1237 4. Instruction 1239 5. Report 1241 6. Suppression 1243 While the pre-configuration is not delivered as part of the Control 1244 Protocol, the same JSON data model is used for consistency and to aid 1245 the reader. 1247 // Pre-Configuration 1249 { 1250 "ma-config": { 1251 "ma-agent-id": "550e8400-e29b-41d4-a716-446655440000", 1252 "ma-control-tasks": [ 1253 { 1254 "ma-task-name": "Controller configuration", 1255 "ma-task-registry-entry": "urn:ietf:lmap:control:http_controller_configuration" 1256 } 1257 ] 1258 "ma-control-channels": [ 1259 { 1260 "ma-channel-name": "Controller channel", 1261 "ma-channel-target": "http://www.example.com/lmap/controller", 1262 "ma-channel-credientials": { } // structure of certificate ommitted for brevity 1263 } 1264 ] 1265 "ma-control-schedules": [ 1266 { 1267 "ma-schedule-name": "pre-configured schedule", 1268 "ma-schedule-tasks": { 1269 { 1270 "ma-schedule-task-name": "Controller configuration", 1271 "ma-schedule-channels": [ 1272 { 1273 "ma-schedule-channel-interface-selection": [1], 1274 "ma-schedule-task-source-channel-names": ["Controller channel"] 1275 } 1276 ] 1277 } 1278 } 1279 "ma-schedule-timing": { 1280 "ma-timing-name": "startup plus up to one hour", 1281 "ma-timing-startup": { 1282 } 1283 "ma-timing-random-spread": "3600000" 1284 } 1285 } 1286 ] 1287 "ma-credentials": { } // structure of certificate ommitted for brevity 1288 } 1289 } 1291 Given the pre-configuration information the MA is able to contact the 1292 Controller and receive an updated/expanded Configuration. In this 1293 example additional Control Protocol tasks to post Status and 1294 Capabilities to the Controller and fetch the Instruction are added as 1295 well as moving the schedule timing for contacting the Controller to 1296 hourly. 1298 // Configuration 1300 { 1301 "ma-config": { 1302 "ma-agent-id": "550e8400-e29b-41d4-a716-446655440000", 1303 "ma-control-tasks": [ 1304 { 1305 "ma-task-name": "Controller configuration", 1306 "ma-task-registry-entry": "urn:ietf:lmap:control:http_controller_configuration" 1307 }, 1308 { 1309 "ma-task-name": "Controller status and capabilities", 1310 "ma-task-registry-entry": "urn:ietf:lmap:control:http_controller_status_and_capabilities" 1311 }, 1312 { 1313 "ma-task-name": "Controller instruction", 1314 "ma-task-registry-entry": "urn:ietf:lmap:control:http_controller_instruction" 1315 } 1316 ] 1317 "ma-control-channels": [ 1318 { 1319 "ma-channel-name": "Controller instruction", 1320 "ma-channel-target": "http://www.example.com/lmap/controller", 1321 "ma-channel-credientials": { } // structure of certificate ommitted for brevity 1322 } 1323 ] 1324 "ma-control-schedules": [ 1325 { 1326 "ma-schedule-name": "Controller schedule", 1327 "ma-schedule-tasks": [ 1328 { 1329 "ma-schedule-task-name": "Controller configuration", 1330 "ma-schedule-channels": [ 1331 { 1332 "ma-schedule-channel-interface-selection": [1], 1333 "ma-schedule-task-source-channel-names": ["Controller channel"] 1334 } 1335 ] 1336 }, 1337 { 1338 "ma-schedule-task-name": "Controller status and capabilities", 1339 "ma-schedule-channels": [ 1340 { 1341 "ma-schedule-channel-interface-selection": [1], 1342 "ma-schedule-task-source-channel-names": ["Controller channel"] 1343 } 1344 ] 1345 }, 1346 { 1347 "ma-schedule-task-name": "Controller instruction", 1348 "ma-schedule-channels": [ 1349 { 1350 "ma-schedule-channel-interface-selection": [1], 1351 "ma-schedule-task-source-channel-names": ["Controller channel"] 1352 } 1353 ] 1354 } 1355 ] 1356 "ma-schedule-timing": { 1357 "ma-timing-name": "hourly randomly", 1358 "ma-timing-calendar": { 1359 "ma-calendar-minutes": ["00"], 1360 "ma-calendar-seconds": ["00"] 1361 } 1362 "ma-timing-random-spread": "3600000" 1363 } 1364 } 1365 ] 1366 "ma-credentials": { } // structure of certificate ommitted for brevity 1367 } 1368 } 1370 The above configuration now contacts the Controller randomnly within 1371 each hour. The following is an example of the Status and 1372 Capabilities information that is transferred from the MA to the 1373 Controller. 1375 // Status and Capabilities 1377 { 1378 ma-status-and-capabilities { 1379 "ma-agent-id": "550e8400-e29b-41d4-a716-446655440000", 1380 "ma-device-id": "urn:dev:mac:0024befffe804ff1" 1381 "ma-hardware": "mfr-home-gateway-v10" 1382 "ma-firmware": "25637748-rev2a" 1383 "ma-version": "ispa-v1.01" 1384 "ma-interfaces: [ 1385 { 1386 "ma-interface-name": "broadband", 1387 "ma-interface-type": "PPPoE" 1388 } 1389 ] 1390 "ma-last-measurement: "", 1391 "ma-last-report: "", 1392 "ma-last-instruction: "", 1393 "ma-last-configuration: "2014-06-08T22:47:31+00:00", 1394 "ma-supported-tasks: [ 1395 { 1396 "ma-task-name": "Controller configuration", 1397 "ma-task-registry": "urn:ietf:lmap:control:http_controller_configuration" 1398 }, 1399 { 1400 "ma-task-name": "Controller status and capabilities", 1401 "ma-task-registry": "urn:ietf:lmap:control:http_controller_status_and_capabilities" 1402 }, 1403 { 1404 "ma-task-name": "Controller instruction", 1405 "ma-task-registry": "urn:ietf:lmap:control:http_controller_instruction" 1406 }, 1407 { 1408 "ma-task-name": "Report", 1409 "ma-task-registry": "urn:ietf:lmap:report:http_report" 1410 }, 1411 { 1412 "ma-task-name": "UDP Latency", 1413 "ma-task-registry": "urn:ietf:ippm:measurement:UDPLatency-Poisson-XthPercentileMean" 1414 } 1415 ] 1416 } 1417 } 1418 After fetching the status and capabilties the Controller issues and 1419 Instruction to the MA to perform a single UDP latency measurement 1420 task 4 times a day and to report the results immediately. 1422 // Instruction 1424 { 1425 "ma-instruction": { 1426 "ma-instruction-tasks": [ 1427 { 1428 "ma-task-name": "UDP Latency", 1429 "ma-task-registry-entry": "urn:ietf:ippm:measurement:UDPLatency-Poisson-XthPercentileMean", 1430 "ma-task-options": [ 1431 {"name": "X", "value": "99"}, 1432 {"name":"rate", "value": "5"}, 1433 {"name":"duration", "value": "30.000"}, 1434 {"name":"interface", "value": "broadband"}, 1435 {"name":"destination-ip", "value": {"version":"ipv4", "ip-address":"192.168.2.54"}}, 1436 {"name":"destination-port", "value": "50000"}, 1437 {"name":"source-port", "value": "50000"} 1438 ], 1439 "ma-task-suppress-by-default": "TRUE" 1440 }, 1441 { 1442 "ma-task-name": "Report", 1443 "ma-task-registry-entry": "urn:ietf:lmap:report:http_report", 1444 "ma-task-options": [ 1445 {"name": "report-with-no-data", "value": "FALSE"} 1446 ], 1447 "ma-task-suppress-by-default": "FALSE" 1448 } 1449 ] 1450 "ma-report-channels": [ 1451 { 1452 "ma-channel-name": "Collector A", 1453 "ma-channel-target": "http://www.example2.com/lmap/collector", 1454 "ma-channel-credientials": { } // structure of certificate ommitted for brevity 1455 } 1456 ] 1457 "ma-instruction-schedules": [ 1458 { 1459 "ma-schedule-name": "4 times daily test UDP latency and report", 1460 "ma-schedule-tasks": { 1461 { 1462 "ma-schedule-task-name": "UDP Latency", 1463 "ma-schedule-downstream-tasks": [ 1464 { 1465 "ma-schedule-task-output-selection": [1], 1466 "ma-schedule-task-downstream-task-configuration-names": "Report" 1467 } 1468 ] 1469 }, 1470 { 1471 "ma-schedule-task-name": "Report", 1472 "ma-schedule-channels": [ 1473 { 1474 "ma-schedule-channel-interface-selection": [1], 1475 "ma-schedule-channel-names": "Collector A" 1476 } 1477 ] 1478 } 1479 } 1480 "ma-schedule-timing": { 1481 "ma-timing-name": "once every 6 hours", 1482 "ma-timing-calendar": { 1483 "ma-calendar-hours": ["00", "06", "12", "18"], 1484 "ma-calendar-minutes": ["00"], 1485 "ma-calendar-seconds": ["00"] 1486 } 1487 "ma-timing-random-spread": "21600000" 1488 } 1489 } 1490 ] 1491 } 1492 } 1494 The report task in the Instruction is executed immediately after the 1495 UDP test and transfers the following data to the Collector. 1497 // Report 1499 { 1500 ma-report: { 1501 "ma-report-date": "2014-06-09T02:30:45+00:00", 1502 "ma-report-agent-id": "550e8400-e29b-41d4-a716-446655440000", 1503 "ma-report-tasks": [ 1504 "ma-report-task-config": { 1505 "ma-task-name": "UDP Latency", 1506 "ma-task-registry-entry": "urn:ietf:ippm:measurement:UDPLatency-Poisson-XthPercentileMean", 1507 "ma-task-options": [ 1508 {"name": "X", "value": "99"}, 1509 {"name":"rate", "value": "5"}, 1510 {"name":"duration", "value": "30.000"}, 1511 {"name":"interface", "value": "broadband"}, 1512 {"name":"destination-ip", "value": {"version":"ipv4", "ip-address":"192.168.2.54"}}, 1513 {"name":"destination-port", "value": "50000"}, 1514 {"name":"source-port", "value": "50000"} 1515 ] 1516 }, 1517 "ma-report-task-column-labels": ["start-time", "conflicting-tasks", "cross-traffic", "mean", "min", "max"], 1518 "ma-report-task-rows": [{"2014-06-09T02:30:10+00:00", "", "0", "20.13", "18.3", "24.1"}] 1519 ] 1520 } 1521 } 1523 The Controller decides that there is a problem with the UDP L:atency 1524 test and issues a Suppression Instruction. Since the task is marked 1525 as suppressable by default, simply turning on suppression will stop 1526 the task being executed in future. 1528 // Suppression 1530 { 1531 "ma-instruction": { 1532 "ma-suppression": { 1533 "ma-suppression-enabled": "TRUE" 1534 { 1535 } 1536 } 1538 7. Acknowledgements 1540 The notation was inspired by the notation used in the ALTO protocol 1541 specification. 1543 Philip Eardley, Trevor Burbridge, Marcelo Bagnulo and Juergen 1544 Schoenwaelder work in part on the Leone research project, which 1545 receives funding from the European Union Seventh Framework Programme 1546 [FP7/2007-2013] under grant agreement number 317647. 1548 8. References 1550 8.1. Normative References 1552 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1553 Requirement Levels", BCP 14, RFC 2119, March 1997. 1555 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 1556 Internet: Timestamps", RFC 3339, July 2002. 1558 8.2. Informative References 1560 [I-D.bagnulo-ippm-new-registry] 1561 Bagnulo, M., Burbridge, T., Crawford, S., Eardley, P., and 1562 A. Morton, "A registry for commonly used metrics", draft- 1563 bagnulo-ippm-new-registry-01 (work in progress), July 1564 2013. 1566 [I-D.ietf-lmap-framework] 1567 Eardley, P., Morton, A., Bagnulo, M., Burbridge, T., 1568 Aitken, P., and A. Akhter, "A framework for large-scale 1569 measurement platforms (LMAP)", draft-ietf-lmap- 1570 framework-03 (work in progress), January 2014. 1572 [RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between 1573 Information Models and Data Models", RFC 3444, January 1574 2003. 1576 Authors' Addresses 1578 Trevor Burbridge 1579 BT 1580 Adastral Park, Martlesham Heath 1581 Ipswich IP5 3RE 1582 United Kingdom 1584 Email: trevor.burbridge@bt.com 1585 Philip Eardley 1586 BT 1587 Adastral Park, Martlesham Heath 1588 Ipswich IP5 3RE 1589 United Kingdom 1591 Email: philip.eardley@bt.com 1593 Marcelo Bagnulo 1594 Universidad Carlos III de Madrid 1595 Av. Universidad 30 1596 Leganes, Madrid 28911 1597 Spain 1599 Email: marcelo@it.uc3m.es 1601 Juergen Schoenwaelder 1602 Jacobs University Bremen 1603 Campus Ring 1 1604 Bremen 28759 1605 Germany 1607 Email: j.schoenwaelder@jacobs-university.de