idnits 2.17.1 draft-ietf-lmap-information-model-18.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 756 has weird spacing: '...ion-obj ma-in...' == Line 945 has weird spacing: '...ask-obj ma-ca...' == Line 991 has weird spacing: '...ace-obj ma-...' == Line 993 has weird spacing: '...ion-obj ma-st...' == Line 1027 has weird spacing: '...ion-obj ma-...' == (7 more instances...) -- The document date (April 21, 2017) is 2524 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 (-24) exists of draft-ietf-ippm-metric-registry-10 == Outdated reference: A later version (-12) exists of draft-ietf-lmap-yang-10 Summary: 0 errors (**), 0 flaws (~~), 10 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: October 23, 2017 M. Bagnulo 6 Universidad Carlos III de Madrid 7 J. Schoenwaelder 8 Jacobs University Bremen 9 April 21, 2017 11 Information Model for Large-Scale Measurement Platforms (LMAP) 12 draft-ietf-lmap-information-model-18 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 Measurement Agent or 19 exists in communications with a Controller or Collector within an 20 LMAP framework. The purpose of such an Information Model is to 21 provide a protocol and device independent view of the Measurement 22 Agent that can be implemented via one or more Control and Report 23 protocols. 25 Requirements Language 27 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 28 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 29 document are to be interpreted as described in RFC 2119 [RFC2119]. 31 Status of This Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at http://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on October 23, 2017. 48 Copyright Notice 50 Copyright (c) 2017 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents 55 (http://trustee.ietf.org/license-info) in effect on the date of 56 publication of this document. Please review these documents 57 carefully, as they describe your rights and restrictions with respect 58 to this document. Code Components extracted from this document must 59 include Simplified BSD License text as described in Section 4.e of 60 the Trust Legal Provisions and are provided without warranty as 61 described in the Simplified BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 66 2. Notation . . . . . . . . . . . . . . . . . . . . . . . . . . 5 67 3. LMAP Information Model . . . . . . . . . . . . . . . . . . . 6 68 3.1. Pre-Configuration Information . . . . . . . . . . . . . . 10 69 3.1.1. Definition of ma-preconfig-obj . . . . . . . . . . . 11 70 3.2. Configuration Information . . . . . . . . . . . . . . . . 11 71 3.2.1. Definition of ma-config-obj . . . . . . . . . . . . . 13 72 3.3. Instruction Information . . . . . . . . . . . . . . . . . 14 73 3.3.1. Definition of ma-instruction-obj . . . . . . . . . . 16 74 3.3.2. Definition of ma-suppression-obj . . . . . . . . . . 17 75 3.4. Logging Information . . . . . . . . . . . . . . . . . . . 18 76 3.4.1. Definition of ma-log-obj . . . . . . . . . . . . . . 20 77 3.5. Capability and Status Information . . . . . . . . . . . . 20 78 3.5.1. Definition of ma-capability-obj . . . . . . . . . . . 20 79 3.5.2. Definition of ma-capability-task-obj . . . . . . . . 21 80 3.5.3. Definition of ma-status-obj . . . . . . . . . . . . . 21 81 3.5.4. Definition of ma-status-schedule-obj . . . . . . . . 22 82 3.5.5. Definition of ma-status-action-obj . . . . . . . . . 23 83 3.5.6. Definition of ma-status-suppression-obj . . . . . . . 26 84 3.5.7. Definition of ma-status-interface-obj . . . . . . . . 26 85 3.6. Reporting Information . . . . . . . . . . . . . . . . . . 27 86 3.6.1. Definition of ma-report-obj . . . . . . . . . . . . . 29 87 3.6.2. Definition of ma-report-result-obj . . . . . . . . . 29 88 3.6.3. Definition of ma-report-conflict-obj . . . . . . . . 31 89 3.6.4. Definition of ma-report-table-obj . . . . . . . . . . 32 90 3.6.5. Definition of ma-report-row-obj . . . . . . . . . . . 32 91 3.7. Common Objects: Schedules . . . . . . . . . . . . . . . . 32 92 3.7.1. Definition of ma-schedule-obj . . . . . . . . . . . . 34 93 3.7.2. Definition of ma-action-obj . . . . . . . . . . . . . 35 94 3.8. Common Objects: Channels . . . . . . . . . . . . . . . . 36 95 3.8.1. Definition of ma-channel-obj . . . . . . . . . . . . 37 97 3.9. Common Objects: Task Configurations . . . . . . . . . . . 37 98 3.9.1. Definition of ma-task-obj . . . . . . . . . . . . . . 39 99 3.9.2. Definition of ma-option-obj . . . . . . . . . . . . . 39 100 3.10. Common Objects: Registry Information . . . . . . . . . . 40 101 3.10.1. Definition of ma-registry-obj . . . . . . . . . . . 40 102 3.11. Common Objects: Event Information . . . . . . . . . . . . 40 103 3.11.1. Definition of ma-event-obj . . . . . . . . . . . . . 41 104 3.11.2. Definition of ma-periodic-obj . . . . . . . . . . . 43 105 3.11.3. Definition of ma-calendar-obj . . . . . . . . . . . 43 106 3.11.4. Definition of ma-one-off-obj . . . . . . . . . . . . 45 107 3.11.5. Definition of ma-immediate-obj . . . . . . . . . . . 46 108 3.11.6. Definition of ma-startup-obj . . . . . . . . . . . . 46 109 3.11.7. Definition of ma-controller-lost-obj . . . . . . . . 46 110 3.11.8. Definition of ma-controller-connected-obj . . . . . 46 111 4. Example Execution . . . . . . . . . . . . . . . . . . . . . . 47 112 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48 113 6. Security Considerations . . . . . . . . . . . . . . . . . . . 49 114 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 49 115 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 50 116 8.1. Normative References . . . . . . . . . . . . . . . . . . 50 117 8.2. Informative References . . . . . . . . . . . . . . . . . 50 118 Appendix A. Change History . . . . . . . . . . . . . . . . . . . 51 119 A.1. Non-editorial changes since -17 . . . . . . . . . . . . . 51 120 A.2. Non-editorial changes since -16 . . . . . . . . . . . . . 51 121 A.3. Non-editorial changes since -15 . . . . . . . . . . . . . 51 122 A.4. Non-editorial changes since -14 . . . . . . . . . . . . . 51 123 A.5. Non-editorial changes since -13 . . . . . . . . . . . . . 52 124 A.6. Non-editorial changes since -12 . . . . . . . . . . . . . 52 125 A.7. Non-editorial changes since -11 . . . . . . . . . . . . . 52 126 A.8. Non-editorial changes since -10 . . . . . . . . . . . . . 52 127 A.9. Non-editorial changes since -09 . . . . . . . . . . . . . 52 128 A.10. Non-editorial changes since -08 . . . . . . . . . . . . . 53 129 A.11. Non-editorial changes since -07 . . . . . . . . . . . . . 53 130 A.12. Non-editorial changes since -06 . . . . . . . . . . . . . 53 131 A.13. Non-editorial changes since -05 . . . . . . . . . . . . . 54 132 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 54 134 1. Introduction 136 A large-scale measurement platform is a collection of components that 137 work in a coordinated fashion to perform measurements from a large 138 number of vantage points. A typical use case is the execution of 139 broadband measurements [RFC7536]. The main components of a large- 140 scale measurement platform are the Measurement Agents (hereafter 141 MAs), the Controller(s) and the Collector(s). 143 The MAs are the elements actually performing the measurements. The 144 MAs are controlled by exactly one Controller at a time and the 145 Collectors gather the results generated by the MAs. In a nutshell, 146 the normal operation of a large-scale measurement platform starts 147 with the Controller instructing a set of one or more MAs to perform a 148 set of one or more Measurement Tasks at a certain point in time. The 149 MAs execute the instructions from a Controller, and once they have 150 done so, they report the results of the measurements to one or more 151 Collectors. The overall framework for a large-scale measurement 152 platform as used in this document is described in detail in 153 [RFC7594]. 155 A large-scale measurement platform involves basically three types of 156 protocols, namely, a Control protocol (or protocols) between a 157 Controller and the MAs, a Report protocol (or protocols) between the 158 MAs and the Collector(s) and several measurement protocols between 159 the MAs and Measurement Peers (MPs), used to actually perform the 160 measurements. In addition some information is required to be 161 configured on the MA prior to any communication with a Controller. 163 This document defines the information model for both Control and the 164 Report protocols along with pre-configuration information that is 165 required on the MA before communicating with the Controller, broadly 166 named as the LMAP Information Model. The measurement protocols are 167 out of the scope of this document. 169 As defined in [RFC3444], the LMAP Information Model defines the 170 concepts involved in a large-scale measurement platform at a high 171 level of abstraction, independent of any specific implementation or 172 actual protocol used to exchange the information. It is expected 173 that the proposed information model can be used with different 174 protocols in different measurement platform architectures and across 175 different types of MA devices (e.g., home gateway, smartphone, PC, 176 router). A YANG data model implementing the information model can be 177 found in [I-D.ietf-lmap-yang]. 179 The definition of an Information Model serves a number of purposes: 181 1. To guide the standardisation of one or more Control and Report 182 protocols and data models 184 2. To enable high-level inter-operability between different Control 185 and Report protocols by facilitating translation between their 186 respective data models such that a Controller could instruct sub- 187 populations of MAs using different protocols 189 3. To form agreement of what information needs to be held by an MA 190 and passed over the Control and Report interfaces and support the 191 functionality described in the LMAP framework 193 4. To enable existing protocols and data models to be assessed for 194 their suitability as part of a large-scale measurement system 196 2. Notation 198 This document uses a programming language-like notation to define the 199 properties of the objects of the information model. An optional 200 property is enclosed by square brackets, [ ], and a list property is 201 indicated by two numbers in angle brackets, , where m indicates 202 the minimal number of values, and n is the maximum. The symbol * for 203 n means no upper bound. 205 The object definitions use a couple of base types that are defined as 206 follows: 208 int A type representing signed or unsigned integer numbers. 209 This information model does not define a precision nor 210 does it make a distinction between signed and unsigned 211 number ranges. This type is also used to represent 212 enumerations. 214 boolean A type representing a boolean value. 216 string A type representing a human-readable string consisting of 217 a (possibly restricted) subset of Unicode and ISO/IEC 218 10646 [ISO.10646] characters. 220 datetime A type representing a date and time using the Gregorian 221 calendar. The datetime format MUST conform to RFC 3339 222 [RFC3339]. 224 uuid A type representing Universally Unique IDentifier (UUID( 225 as defined in RFC 4122 [RFC4122]. The UUID values are 226 expected to be unique within an installation of a large- 227 scale measurement system. 229 uri A type representing a Uniform Resource Identifier as 230 defined in STD 66 [RFC3986]. 232 ip-address A type representing an IP address. This type supports 233 both IPv4 and IPv6 addresses. 235 counter A non-negative integer that monotonically increases. 236 Counters may have discontinuities and they are not 237 expected to persist across restarts. 239 credentials An opaque type representing credentials needed by a 240 cryptographic mechanism to secure communication. Data 241 models must expand this opaque type as needed and 242 required by the security protocols utilized. 244 data An opaque type representing data obtained from 245 measurements. 247 Names of objects are generally assumed to be unique within an 248 implementation. 250 3. LMAP Information Model 252 The information described herein relates to the information stored, 253 received or transmitted by a Measurement Agent as described within 254 the LMAP framework [RFC7594]. As such, some subsets of this 255 information model are applicable to the measurement Controller, 256 Collector and any device management system that pre-configures the 257 Measurement Agent. The information described in these models will be 258 transmitted by protocols using interfaces between the Measurement 259 Agent and such systems according to a Data Model. 261 The information model is divided into six aspects. Firstly the 262 grouping of information facilitates reader understanding. Secondly, 263 the particular groupings chosen are expected to map to different 264 protocols or different transmissions within those protocols. 266 1. Pre-Configuration Information. Information pre-configured on the 267 Measurement Agent prior to any communication with other 268 components of the LMAP architecture (i.e., the Controller, 269 Collector and Measurement Peers), specifically detailing how to 270 communicate with a Controller and whether the device is enabled 271 to participate as an MA. 273 2. Configuration Information. Update of the pre-configuration 274 information during the registration of the MA or subsequent 275 communication with the Controller, along with the configuration 276 of further parameters about the MA (rather than the Measurement 277 Tasks it should perform) that were not mandatory for the initial 278 communication between the MA and a Controller. 280 3. Instruction Information. Information that is received by the MA 281 from the Controller pertaining to the Measurement Tasks that 282 should be executed. This includes the task execution Schedules 283 (other than the Controller communication Schedule supplied as 284 (pre)configuration information) and related information such as 285 the Task Configuration, communication Channels to Collectors and 286 schedule Event and Timing information. It also includes Task 287 Suppression information that is used to over-ride normal Task 288 execution. 290 4. Logging Information. Information transmitted from the MA to the 291 Controller detailing the results of any configuration operations 292 along with error and status information from the operation of the 293 MA. 295 5. Capability and Status Information. Information on the general 296 status and capabilities of the MA. For example, the set of 297 measurements that are supported on the device. 299 6. Reporting Information. Information transmitted from the MA to 300 one or more Collectors including measurement results and the 301 context in which they were conducted. 303 In addition the MA may hold further information not described herein, 304 and which may be optionally transferred to or from other systems 305 including the Controller and Collector. One example of information 306 in this category is subscriber or line information that may be 307 extracted by a task and reported by the MA in the reporting 308 communication to a Collector. 310 It should also be noted that the MA may be in communication with 311 other management systems which may be responsible for configuring and 312 retrieving information from the MA device. Such systems, where 313 available, can perform an important role in transferring the pre- 314 configuration information to the MA or enabling/disabling the 315 measurement functionality of the MA. 317 The granularity of data transmitted in each operation of the Control 318 and Report Protocols is not dictated by the Information Model. For 319 example, the Instruction object may be delivered in a single 320 operation. Alternatively, Schedules and Task Configurations may be 321 separated or even each Schedule/Task Configuration may be delivered 322 individually. Similarly the Information Model does not dictate 323 whether data is read, write, or read/write. For example, some 324 Control Protocols may have the ability to read back Configuration and 325 Instruction information which have been previously set on the MA. 326 Lastly, while some protocols may simply overwrite information (for 327 example refreshing the entire Instruction Information), other 328 protocols may have the ability to update or delete selected items of 329 information. 331 The information modeled by the six aspects of the information model 332 is supported by a number of common information objects. These 333 objects are also described later in this document and comprise of: 335 a. Schedules. A set of Schedules tells the MA to execute Actions. 336 An Action of a Schedule leads to the execution of a Task. 337 Without a Schedule no Task (including measurements or reporting 338 or communicating with the Controller) is ever executed. 339 Schedules are used within the Instruction to specify what tasks 340 should be performed, when, and how to direct their results. A 341 Schedule is also used within the pre-Configuration and 342 Configuration information in order to execute the Task or Tasks 343 required to communicate with the Controller. A specific Schedule 344 can only be active once. Attempts to start a Schedule while the 345 same Schedule is still running will fail. 347 b. Channels. A set of Channel objects are used to communicate with 348 a number of endpoints (i.e., the Controller and Collectors). 349 Each Channel object contains the information required for the 350 communication with a single endpoint such as the target location 351 and security details. 353 c. Task Configurations. A set of Task Configurations is used to 354 configure the Tasks that are run by the MA. This includes the 355 registry entries for the Task and any configuration parameters, 356 represented as Task Options. Task Configurations are referenced 357 from a Schedule in order to specify what Tasks the MA should 358 execute. 360 d. Events. A set of Event objects that can be referenced from the 361 Schedules. Each Schedule always references exactly one Event 362 object that determines when the schedule is executed. An Event 363 object specifies either a singleton or series of events that 364 indicate when Tasks should be executed. A commonly used kind of 365 Event objects are Timing objects. For Event objects specifying a 366 series of events, it is generally a good idea to configure an end 367 time and to refresh the end time as needed to ensure that MAs 368 that loose connectivity to their controller do not continue 369 executing Schedules forever. 371 Figure 1 illustrates the structure in which these common information 372 objects are referenced. The references are achieved by each object 373 (Task Configuration, Event) being given a short textual name that is 374 used by other objects. The objects shown in parenthesis are part of 375 the internal object structure of a Schedule. Channels are not shown 376 in the diagram since they are only used as an option by selected Task 377 Configurations but are similarly referenced using a short text name. 379 Schedule 380 |-- triggered by --> Event 381 | 382 |-- executes --> Action 1 383 | |-- using --> Task Configuration 384 | | 385 | `-- feeding to --> Destination Schedule 386 : 387 : 388 `-- executes --> Action N 389 |-- using --> Task Configuration 390 | 391 `-- feeding to --> Destination Schedule 393 Figure 1: Relationship between Schedules, Events, Actions, Task 394 Configurations, and Destination Schedules 396 The primary function of an MA is to execute Schedules. A Schedule, 397 which is triggered by an Event, executes a number of Actions. An 398 Action refers to a Configured Task and it may feed results to a 399 Destination Schedule. Both, Actions and Configured Tasks can provide 400 parameters, represented as Action Options and Task Options. 402 Tasks can implement a variety of different functions. While in terms 403 of the Information Model, all Tasks have the same structure, it can 404 help conceptually to think of different Task categories: 406 1. Measurement Tasks measure some aspect of network performance or 407 traffic. They may also capture contextual information from the 408 MA device or network interfaces such as the device type or 409 interface speed. 411 2. Data Transfer Tasks support the communication with a Controller 412 and Collectors: 414 A. Reporting Tasks report the results of Measurement Tasks to 415 Collectors 417 B. Control Task(s) implement the Control Protocol and 418 communicate with the Controller. 420 3. Data Analysis Tasks can exist to analyse data from other 421 Measurement Tasks locally on the MA 423 4. Data Management Tasks may exist to clean-up, filter or compress 424 data on the MA such as Measurement Task results 426 Figure 1 indicates that Actions can produce data that is fed into 427 Destination Schedules. This can by used by Actions implementing 428 Measurement Tasks to feed measurement results to a Schedule that 429 triggers Actions implementing Reporting Tasks. Data fed to a 430 Destination Schedule is consumed by the first Action of the 431 Destination Schedule if the Destination Schedule is using sequential 432 or pipelined execution mode and it is consumed by all Actions of the 433 Destination Schedule if the Destination Schedule is using parallel 434 execution mode. 436 3.1. Pre-Configuration Information 438 This information is the minimal information that needs to be pre- 439 configured to the MA in order for it to successfully communicate with 440 a Controller during the registration process. Some of the Pre- 441 Configuration Information elements are repeated in the Configuration 442 Information in order to allow an LMAP Controller to update these 443 items. The pre-configuration information also contains some elements 444 that are not under the control of the LMAP framework (such as the 445 device identifier and device security credentials). 447 This Pre-Configuration Information needs to include a URL of the 448 initial Controller from where configuration information can be 449 communicated along with the security information required for the 450 communication including the certificate of the Controller (or the 451 certificate of the Certification Authority which was used to issue 452 the certificate for the Controller). All this is expressed as a 453 Channel. While multiple Channels may be provided in the Pre- 454 Configuration Information they must all be associated with a single 455 Controller (e.g., over different interfaces or network protocols). 457 Where the MA pulls information from the Controller, the Pre- 458 Configuration Information also needs to contain the timing of the 459 communication with the Controller as well as the nature of the 460 communication itself (such as the protocol and data to be 461 transferred). The timing is represented as an Event that invokes a 462 Schedule that executes the Task(s) responsible for communication with 463 the Controller. It is this Task (or Tasks) that implement the 464 Control protocol between the MA and the Controller and utilises the 465 Channel information. The Task(s) may take additional parameters, as 466 defined by a Task Configuration. 468 Even where information is pushed to the MA from the Controller 469 (rather than pulled by the MA), a Schedule still needs to be 470 supplied. In this case the Schedule will simply execute a Controller 471 listener Task when the MA is started. A Channel is still required 472 for the MA to establish secure communication with the Controller. 474 It can be seen that these Channels, Schedules and Task Configurations 475 for the initial MA-Controller communication are no different in terms 476 of the Information Model to any other Channel, Schedule or Task 477 Configuration that might execute a Measurement Task or report the 478 measurement results (as described later). 480 The MA may be pre-configured with an MA ID, or may use a Device ID in 481 the first Controller contact before it is assigned an MA ID. The 482 Device ID may be a MAC address or some other device identifier 483 expressed as a URI. If the MA ID is not provided at this stage, then 484 it must be provided by the Controller during Configuration. 486 3.1.1. Definition of ma-preconfig-obj 488 object { 489 [uuid ma-preconfig-agent-id;] 490 ma-task-obj ma-preconfig-control-tasks<1..*>; 491 ma-channel-obj ma-preconfig-control-channels<1..*>; 492 ma-schedule-obj ma-preconfig-control-schedules<1..*>; 493 [uri ma-preconfig-device-id;] 494 credentials ma-preconfig-credentials; 495 } ma-preconfig-obj; 497 The ma-preconfig-obj describes information that needs to be available 498 to the MA in order to bootstrap communication with a Controller. The 499 ma-preconfig-obj consists of the following elements: 501 ma-preconfig-agent-id: An optional uuid uniquely identifying 502 the measurement agent. 504 ma-preconfig-control-tasks: An unordered set of task objects. 506 ma-preconfig-control-channels: An unordered set of channel objects. 508 ma-preconfig-control-schedules: An unordered set of scheduling 509 objects. 511 ma-preconfig-device-id: An optional identifier for the 512 device. 514 ma-preconfig-credentials: The security credentials used by the 515 measurement agent. 517 3.2. Configuration Information 519 During registration or at any later point at which the MA contacts 520 the Controller (or vice-versa), the choice of Controller, details for 521 the timing of communication with the Controller or parameters for the 522 communication Task(s) can be changed (as captured by the Channels, 523 Schedules and Task Configurations objects). For example the pre- 524 configured Controller (specified as a Channel or Channels) may be 525 over-ridden with a specific Controller that is more appropriate to 526 the MA device type, location or characteristics of the network (e.g., 527 access technology type or broadband product). The initial 528 communication Schedule may be over-ridden with one more relevant to 529 routine communications between the MA and the Controller. 531 While some Control protocols may only use a single Schedule, other 532 protocols may use several Schedules (and related data transfer Tasks) 533 to update the Configuration Information, transfer the Instruction 534 Information, transfer Capability and Status Information and send 535 other information to the Controller such as log or error 536 notifications. Multiple Channels may be used to communicate with the 537 same Controller over multiple interfaces (e.g., to send logging 538 information over a different network). 540 In addition the MA will be given further items of information that 541 relate specifically to the MA rather than the measurements it is to 542 conduct or how to report results. The assignment of an ID to the MA 543 is mandatory. If the MA Agent ID was not optionally provided during 544 the pre-configuration then one must be provided by the Controller 545 during Configuration. Optionally a Group ID may also be given which 546 identifies a group of interest to which that MA belongs. For example 547 the group could represent an ISP, broadband product, technology, 548 market classification, geographic region, or a combination of 549 multiple such characteristics. Additional flags control whether the 550 MA ID or the Group ID are included in Reports. The reporting of a 551 Group ID without the MA ID may allow the MA to remain anonymous, 552 which may be particularly useful to prevent tracking of mobile MA 553 devices. 555 Optionally an MA can also be configured to stop executing any 556 Instruction Schedule if the Controller is unreachable. This can be 557 used as a fail-safe to stop Measurement and other Tasks being 558 conducted when there is doubt that the Instruction Information is 559 still valid. This is simply represented as a time window in seconds 560 since the last communication with the Controller after which an Event 561 is generated that can trigger the suspension of Instruction 562 Schedules. The appropriate value of the time window will depend on 563 the specified communication Schedule with the Controller and the 564 duration for which the system is willing to tolerate continued 565 operation with potentially stale Instruction Information. 567 While Pre-Configuration Information is persistent upon device reset 568 or power cycle, the persistency of the Configuration Information may 569 be device dependent. Some devices may revert back to their pre- 570 configuration state upon reboot or factory reset, while other devices 571 may store all Configuration and Instruction information in persistent 572 storage. A Controller can check whether an MA has the latest 573 Configuration and Instruction information by examining the Capability 574 and Status information for the MA. 576 3.2.1. Definition of ma-config-obj 578 object { 579 uuid ma-config-agent-id; 580 ma-task-obj ma-config-control-tasks<1..*>; 581 ma-channel-obj ma-config-control-channels<1..*>; 582 ma-schedule-obj ma-config-control-schedules<1..*>; 583 credentials ma-config-credentials; 584 [string ma-config-group-id;] 585 [string ma-config-measurement-point;] 586 [boolean ma-config-report-agent-id;] 587 [boolean ma-config-report-group-id;] 588 [boolean ma-config-report-measurement-point;] 589 [int ma-config-controller-timeout;] 590 } ma-config-obj; 592 The ma-config-obj consists of the following elements: 594 ma-config-agent-id: A uuid uniquely identifying the 595 measurement agent. 597 ma-config-control-tasks: An unordered set of task objects. 599 ma-config-control-channels: An unordered set of channel 600 objects. 602 ma-config-control-schedules: An unordered set of scheduling 603 objects. 605 ma-config-credentials: The security credentials used by 606 the measurement agent. 608 ma-config-group-id: An optional identifier of the 609 group of measurement agents this 610 measurement agent belongs to. 612 ma-config-measurement-point: An optional identifier for the 613 measurement point indicating 614 where the measurement agent is 615 located on a path (see [RFC7398] 616 for further details). 618 ma-config-report-agent-id: An optional flag indicating 619 whether the agent identifier (ma- 620 config-agent-id) is included in 621 reports. The default value is 622 true. 624 ma-config-report-group-id: An optional flag indicating 625 whether the group identifier (ma- 626 config-group-id) is included in 627 reports. The default value is 628 false. 630 ma-config-report-measurement-point: An optional flag indicating 631 whether the measurement point 632 (ma-config-measurement-point) 633 should be included in reports. 634 The default value is false. 636 ma-config-controller-timeout: A timer is started after each 637 successful contact with a 638 controller. When the timer 639 reaches the controller-timeout 640 (measured in seconds), an event 641 is raised indicating that 642 connectivity to the controller 643 has been lost (see ma-controller- 644 lost-obj). 646 3.3. Instruction Information 648 The Instruction information model has four sub-elements: 650 1. Instruction Task Configurations 652 2. Report Channels 654 3. Instruction Schedules 656 4. Suppression 658 The Instruction supports the execution of all Tasks on the MA except 659 those that deal with communication with the Controller (specified in 660 (pre-)configuration information). The Tasks are configured in 661 Instruction Task Configurations and included by reference in the 662 Actions of Instruction Schedules that specify when to execute them. 663 The results can be communicated to other Schedules or a Task may 664 implement a Reporting Protocol and communicate results over Report 665 Channels. Suppression is used to temporarily stop the execution of 666 new Tasks as specified by the Instruction Schedules (and optionally 667 to stop ongoing Tasks). 669 A Task Configuration is used to configure the mandatory and optional 670 parameters of a Task. It also serves to instruct the MA about the 671 Task including the ability to resolve the Task to an executable and 672 specifying the schema for the Task parameters. 674 A Report Channel defines how to communicate with a single remote 675 system specified by a URL. A Report Channel is used to send results 676 to a single Collector but is no different in terms of the Information 677 Model to the Control Channel used to transfer information between the 678 MA and the Controller. Several Report Channels can be defined to 679 enable results to be split or duplicated across different 680 destinations. A single Channel can be used by multiple (reporting) 681 Task Configurations to transfer data to the same Collector. A single 682 Reporting Task Configuration can also be included in multiple 683 Schedules. E.g., a single Collector may receive data at three 684 different cycle rates, one Schedule reporting hourly, another 685 reporting daily and a third specifying that results should be sent 686 immediately for on-demand measurement tasks. Alternatively multiple 687 Report Channels can be used to send Measurement Task results to 688 different Collectors. The details of the Channel element is 689 described later as it is common to several objects. 691 Instruction Schedules specify which Actions to execute according to a 692 given triggering Event. An Action extends a Configured Task with 693 additional specific parameters. An Event can trigger the execution 694 of a single Action or it can trigger a repeated series of Actions. 695 The Schedule also specifies how to link Tasks output data to other 696 Schedules. 698 Measurement Suppression information is used to over-ride the 699 Instruction Schedule and temporarily stop measurements or other Tasks 700 from running on the MA for a defined or indefinite period. While 701 conceptually measurements can be stopped by simply removing them from 702 the Measurement Schedule, splitting out separate information on 703 Measurement Suppression allows this information to be updated on the 704 MA on a different timing cycle or protocol implementation to the 705 Measurement Schedule. It is also considered that it will be easier 706 for a human operator to implement a temporary explicit suppression 707 rather than having to move to a reduced Schedule and then roll-back 708 at a later time. 710 It should be noted that control schedules and tasks cannot be 711 suppressed as evidenced by the lack of suppression information in the 712 Configuration. The control schedule must only reference tasks listed 713 as control tasks (i.e., within the Configuration information). 715 A single Suppression object is able to enable/disable a set of 716 Instruction Tasks that are tagged for suppression. This enables fine 717 grained control on which Tasks are suppressed. Suppression of both 718 matching Actions and Measurement Schedules is supported. Support for 719 disabling specific Actions allows malfunctioning or mis-configured 720 Tasks or Actions that have an impact on a particular part of the 721 network infrastructure (e.g., a particular Measurement Peer) to be 722 targeted. Support for disabling specific Schedules allows for 723 particularly heavy cycles or sets of less essential Measurement Tasks 724 to be suppressed quickly and effectively. Note that Suppression has 725 no effect on either Controller Tasks or Controller Schedules. 727 Suppression stops new Tasks from executing. In addition, the 728 Suppression information also supports an additional Boolean that is 729 used to select whether on-going tasks are also to be terminated. 731 Unsuppression is achieved through either overwriting the Measurement 732 Suppression information (e.g., changing 'enabled' to False) or 733 through the use of an End time such that the Measurement Suppression 734 will no longer be in effect beyond this time. 736 The goal when defining these four different elements is to allow each 737 part of the information model to change without affecting the other 738 three elements. For example it is envisaged that the Report Channels 739 and the set of Task Configurations will be relatively static. The 740 Instruction Schedule, on the other hand, is likely to be more 741 dynamic, as the measurement panel and test frequency are changed for 742 various business goals. Another example is that measurements can be 743 suppressed with a Suppression command without removing the existing 744 Instruction Schedules that would continue to apply after the 745 Suppression expires or is removed. In terms of the Controller-MA 746 communication this can reduce the data overhead. It also encourages 747 the re-use of the same standard Task Configurations and Reporting 748 Channels to help ensure consistency and reduce errors. 750 3.3.1. Definition of ma-instruction-obj 752 object { 753 ma-task-obj ma-instruction-tasks<0..*>; 754 ma-channel-obj ma-instruction-channels<0..*>; 755 ma-schedule-obj ma-instruction-schedules<0..*>; 756 [ma-suppression-obj ma-instruction-suppressions<0..*>;] 757 } ma-instruction-obj; 759 An ma-instruction-obj consists of the following elements: 761 ma-instruction-tasks: A possibly empty unordered set of task 762 objects. 764 ma-instruction-channels: A possibly empty unordered set of 765 channel objects. 767 ma-instruction-schedules: A possibly empty unordered set of 768 schedule objects. 770 ma-instruction-suppressions: An optional possibly empty unordered 771 set of suppression objects. 773 3.3.2. Definition of ma-suppression-obj 775 object { 776 string ma-suppression-name; 777 [ma-event-obj ma-suppression-start;] 778 [ma-event-obj ma-suppression-end;] 779 [string ma-suppression-match<0..*>;] 780 [boolean ma-suppression-stop-running;] 781 } ma-suppression-obj; 783 The ma-suppression-obj controls the suppression of schedules or 784 actions and consists of the following elements: 786 ma-suppression-name: A name uniquely identifying a 787 suppression. 789 ma-suppression-start: The optional event indicating when 790 suppression starts. If not present, 791 the suppression starts immediately, 792 i.e., as if the value would be 793 'immediate'. 795 ma-suppression-end: The optional event indicating when 796 suppression ends. If not present, the 797 suppression does not have a defined 798 end, i.e., the suppression remains for 799 an indefinite period of time. 801 ma-suppression-match: An optional and possibly empty 802 unordered set of match patterns. The 803 suppression will apply to all schedules 804 (and their actions) that have a 805 matching value in their ma-schedule- 806 suppression-tags and all actions that 807 have a matching value in their ma- 808 action-suppression-tags. Pattern 809 matching is done using glob style 810 pattern (see below). 812 ma-suppression-stop-running: An optional boolean indicating whether 813 suppression will stop any running 814 matching schedules or actions. The 815 default value for this boolean is 816 false. 818 Glob style pattern matching is following POSIX.2 fnmatch() [POSIX.2] 819 without special treatment of file paths: 821 * matches a sequence of characters 822 ? matches a single character 823 [seq] matches any character in seq 824 [!seq] matches any character not in seq 826 A backslash followed by a character matches the following character. 827 In particular: 829 \* matches * 830 \? matches ? 831 \\ matches \ 833 A sequence seq may be a sequence of characters (e.g., [abc] or a 834 range of characters (e.g., [a-c]). 836 3.4. Logging Information 838 The MA may report on the success or failure of Configuration or 839 Instruction communications from the Controller. In addition further 840 operational logs may be produced during the operation of the MA and 841 updates to capabilities may also be reported. Reporting this 842 information is achieved in exactly the same manner as scheduling any 843 other Task. We make no distinction between a Measurement Task 844 conducting an active or passive network measurement and one which 845 solely retrieves static or dynamic information from the MA such as 846 capabilities or logging information. One or more logging tasks can 847 be programmed or configured to capture subsets of the Logging 848 Information. These logging tasks are then executed by Schedules 849 which also specify that the resultant data is to be transferred over 850 the Controller Channels. 852 The type of Logging Information will fall into three different 853 categories: 855 1. Success/failure/warning messages in response to information 856 updates from the Controller. Failure messages could be produced 857 due to some inability to receive or parse the Controller 858 communication, or if the MA is not able to act as instructed. 859 For example: 861 * "Measurement Schedules updated OK" 863 * "Unable to parse JSON" 865 * "Missing mandatory element: Measurement Timing" 867 * "'Start' does not conform to schema - expected datetime" 869 * "Date specified is in the past" 871 * "'Hour' must be in the range 1..24" 873 * "Schedule A refers to non-existent Measurement Task 874 Configuration" 876 * "Measurement Task Configuration X registry entry Y not found" 878 * "Updated Measurement Task Configurations do not include M used 879 by Measurement Schedule N" 881 2. Operational updates from the MA. For example: 883 * "Out of memory: cannot record result" 885 * "Collector 'collector.example.com' not responding" 887 * "Unexpected restart" 889 * "Suppression timeout" 891 * "Failed to execute Measurement Task Configuration H" 893 3. Status updates from the MA. For example: 895 * "Device interface added: eth3" 897 * "Supported measurements updated" 899 * "New IP address on eth0: xxx.xxx.xxx.xxx" 901 This Information Model document does not detail the precise format of 902 logging information since it is to a large extent protocol and MA 903 specific. However, some common information can be identified. 905 3.4.1. Definition of ma-log-obj 907 object { 908 uuid ma-log-agent-id; 909 datetime ma-log-event-time; 910 int ma-log-code; 911 string ma-log-description; 912 } ma-log-obj; 914 The ma-log-obj models the generic aspects of a logging object and 915 consists of the following elements: 917 ma-log-agent-id: A uuid uniquely identifying the measurement 918 agent. 920 ma-log-event-time: The date and time of the event reported in 921 the logging object. 923 ma-log-code: A machine readable code describing the 924 event. 926 ma-log-description: A human readable description of the event. 928 3.5. Capability and Status Information 930 The MA will hold Capability Information that can be retrieved by a 931 Controller. Capabilities include the device interface details 932 available to Measurement Tasks as well as the set of Measurement 933 Tasks/Roles (specified by registry entries) that are actually 934 installed or available on the MA. Status information includes the 935 times that operations were last performed such as contacting the 936 Controller or producing Reports. 938 3.5.1. Definition of ma-capability-obj 940 object { 941 string ma-capability-hardware; 942 string ma-capability-firmware; 943 string ma-capability-version; 944 [string ma-capability-tags<0..*>;] 945 [ma-capability-task-obj ma-capability-tasks<0..*>;] 946 } ma-capability-obj; 948 The ma-capability-obj provides information about the capabilities of 949 the measurement agent and consists of the following elements: 951 ma-capability-hardware: A description of the hardware of the device 952 the measurement agent is running on. 954 ma-capability-firmware: A description of the firmware of the device 955 the measurement agent is running on. 957 ma-capability-version: The version of the measurement agent. 959 ma-capability-tags: An optional unordered set of tags that 960 provide additional information about the 961 capabilities of the measurement agent. 963 ma-capability-tasks: An optional unordered set of capability 964 objects for each supported task. 966 3.5.2. Definition of ma-capability-task-obj 968 object { 969 string ma-capability-task-name; 970 ma-registry-obj ma-capability-task-functions<0..*>; 971 string ma-capability-task-version; 972 } ma-capability-task-obj; 974 The ma-capability-task-obj provides information about the capability 975 of a task and consists of the following elements: 977 ma-capability-task-name: A name uniquely identifying a task. 979 ma-capability-task-functions: A possibly empty unordered set of 980 registry entries identifying 981 functions this task implements. 983 ma-capability-task-version: The version of the measurement task. 985 3.5.3. Definition of ma-status-obj 987 object { 988 uuid ma-status-agent-id; 989 [uri ma-status-device-id;] 990 datetime ma-status-last-started; 991 ma-status-interface-obj ma-status-interfaces<0..*>; 992 [ma-status-schedule-obj ma-status-schedules<0..*>;] 993 [ma-status-suppression-obj ma-status-suppressions<0..*>;] 994 } ma-status-obj; 996 The ma-status-obj provides status information about the measurement 997 agent and consists of the following elements: 999 ma-status-agent-id: A uuid uniquely identifying the measurement 1000 agent. 1002 ma-status-device-id: A URI identifying the device. 1004 ma-status-last-started: The date and time the measurement agent 1005 last started. 1007 ma-status-interfaces: An unordered set of network interfaces 1008 available on the device. 1010 ma-status-schedules: An optional unordered set of status objects 1011 for each schedule. 1013 ma-status-suppressions: An optional unordered set of status objects 1014 for each suppression. 1016 3.5.4. Definition of ma-status-schedule-obj 1018 object { 1019 string ma-status-schedule-name; 1020 string ma-status-schedule-state; 1021 int ma-status-schedule-storage; 1022 counter ma-status-schedule-invocations; 1023 counter ma-status-schedule-suppressions; 1024 counter ma-status-schedule-overlaps; 1025 counter ma-status-schedule-failures; 1026 datetime ma-status-schedule-last-invocation; 1027 [ma-status-action-obj ma-status-schedule-actions<0..*>;] 1028 } ma-status-schedule-obj; 1030 The ma-status-schedule-obj provides status information about the 1031 status of a schedule and consists of the following elements: 1033 ma-status-schedule-name: The name of the schedule this 1034 status object refers to. 1036 ma-status-schedule-state: The state of the schedule. The 1037 value 'enabled' indicates that 1038 the schedule is currently 1039 enabled. The value 'suppressed' 1040 indicates that the schedule is 1041 currently suppressed. The value 1042 'disabled' indicates that the 1043 schedule is currently disabled. 1044 The value 'running' indicates 1045 that the schedule is currently 1046 running. 1048 ma-status-schedule-storage: The amount of secondary storage 1049 (e.g., allocated in a file 1050 system) holding temporary data 1051 allocated to the schedule in 1052 bytes. This object reports the 1053 amount of allocated physical 1054 storage and not the storage used 1055 by logical data records. Data 1056 models should use a 64-bit 1057 integer type. 1059 ma-status-schedule-invocations Number of invocations of this 1060 schedule. This counter does not 1061 include suppressed invocations or 1062 invocations that were prevented 1063 due to an overlap with a previous 1064 invocation of this schedule. 1066 ma-status-schedule-suppressions Number of suppressed executions 1067 of this schedule. 1069 ma-status-schedule-overlaps Number of executions prevented 1070 due to overlaps with a previous 1071 invocation of this schedule. 1073 ma-status-schedule-failures Number of failed executions of 1074 this schedule. A failed 1075 execution is an execution where 1076 at least one action failed. 1078 ma-status-schedule-last-invocation: The date and time of the last 1079 invocation of this schedule. 1081 ma-status-schedule-actions: An optional ordered list of 1082 status objects for each action of 1083 the schedule. 1085 3.5.5. Definition of ma-status-action-obj 1086 object { 1087 string ma-status-action-name; 1088 string ma-status-action-state; 1089 int ma-status-action-storage; 1090 counter ma-status-action-invocations; 1091 counter ma-status-action-suppressions; 1092 counter ma-status-action-overlaps; 1093 counter ma-status-action-failures; 1094 datetime ma-status-action-last-invocation; 1095 datetime ma-status-action-last-completion; 1096 int ma-status-action-last-status; 1097 string ma-status-action-last-message; 1098 datetime ma-status-action-last-failed-completion; 1099 int ma-status-action-last-failed-status; 1100 string ma-status-action-last-failed-message; 1101 } ma-status-action-obj; 1103 The ma-status-action-obj provides status information about an action 1104 of a schedule and consists of the following elements: 1106 ma-status-action-name: The name of the action of a 1107 schedule this status object 1108 refers to. 1110 ma-status-action-state: The state of the action. 1111 The value 'enabled' 1112 indicates that the action is 1113 currently enabled. The 1114 value 'suppressed' indicates 1115 that the action is currently 1116 suppressed. The value 1117 'disabled' indicates that 1118 the action is currently 1119 disabled. The value 1120 'running' indicates that the 1121 action is currently running. 1123 ma-status-action-storage: The amount of secondary 1124 storage (e.g., allocated in 1125 a file system) holding 1126 temporary data allocated to 1127 the action in bytes. This 1128 object reports the amount of 1129 allocated physical storage 1130 and not the storage used by 1131 logical data records. Data 1132 models should use a 64-bit 1133 integer type. 1135 ma-status-action-invocations Number of invocations of 1136 this action. This counter 1137 does not include suppressed 1138 invocations or invocations 1139 that were prevented due to 1140 an overlap with a previous 1141 invocation of this action. 1143 ma-status-action-suppressions Number of suppressed 1144 executions of this action. 1146 ma-status-action-overlaps Number of executions 1147 prevented due to overlaps 1148 with a previous invocation 1149 of this action. 1151 ma-status-action-failures Number of failed executions 1152 of this action. 1154 ma-status-action-last-invocation: The date and time of the 1155 last invocation of this 1156 action. 1158 ma-status-action-last-completion: The date and time of the 1159 last completion of this 1160 action. 1162 ma-status-action-last-status: The status code returned by 1163 the last execution of this 1164 action. 1166 ma-status-action-last-message: The status message produced 1167 by the last execution of 1168 this action. 1170 ma-status-action-last-failed-completion: The date and time of the 1171 last failed completion of 1172 this action. 1174 ma-status-action-last-failed-status: The status code returned by 1175 the last failed execution of 1176 this action. 1178 ma-status-action-last-failed-message: The status message produced 1179 by the last failed execution 1180 of this action. 1182 3.5.6. Definition of ma-status-suppression-obj 1184 object { 1185 string ma-status-suppression-name; 1186 string ma-status-suppression-state; 1187 } ma-status-suppression-obj; 1189 The ma-status-suppression-obj provides status information about that 1190 status of a suppression and consists of the following elements: 1192 ma-status-suppression-name: The name of the suppression this status 1193 object refers to. 1195 ma-status-suppression-state: The state of the suppression. The 1196 value 'enabled' indicates that the 1197 suppression is currently enabled. The 1198 value 'active indicates that the 1199 suppression is currently active. The 1200 value 'disabled' indicates that the 1201 suppression is currently disabled. 1203 3.5.7. Definition of ma-status-interface-obj 1205 object { 1206 string ma-status-interface-name; 1207 string ma-status-interface-type; 1208 [int ma-status-interface-speed;] 1209 [string ma-status-interface-link-layer-address;] 1210 [ip-address ma-status-interface-ip-addresses<0..*>;] 1211 [ip-address ma-status-interface-gateways<0..*>;] 1212 [ip-address ma-status-interface-dns-servers<0..*>;] 1213 } ma-status-interface-obj; 1215 The ma-status-interface-obj provides status information about network 1216 interfaces and consists of the following elements: 1218 ma-status-interface-name: A name uniquely identifying a 1219 network interface. 1221 ma-status-interface-type: The type of the network 1222 interface. 1224 ma-status-interface-speed: An optional indication of the 1225 speed of the interface 1226 (measured in bits-per- 1227 second). 1229 ma-status-interface-link-layer-address: An optional link-layer 1230 address of the interface. 1232 ma-status-interface-ip-addresses: An optional ordered list of 1233 IP addresses assigned to the 1234 interface. 1236 ma-status-interface-gateways: An optional ordered list of 1237 gateways assigned to the 1238 interface. 1240 ma-status-interface-dns-servers: An optional ordered list of 1241 DNS servers assigned to the 1242 interface. 1244 3.6. Reporting Information 1246 At a point in time specified by a Schedule, the MA will execute tasks 1247 that communicate a set of measurement results to the Collector. 1248 These Reporting Tasks will be configured to transmit task results 1249 over a specified Report Channel to a Collector. 1251 It should be noted that the output from Tasks does not need to be 1252 sent to communication Channels. It can alternatively, or 1253 additionally, be sent to other Tasks on the MA. This facilitates 1254 using a first Measurement Task to control the operation of a later 1255 Measurement Task (such as first probing available line speed and then 1256 adjusting the operation of a video testing measurement) and also to 1257 allow local processing of data to output alarms (e.g., when 1258 performance drops from earlier levels). Of course, subsequent Tasks 1259 also include Tasks that implement the reporting protocol(s) and 1260 transfer data to one or more Collector(s). 1262 The Report generated by a Reporting Task is structured hierarchically 1263 to avoid repetition of report header and Measurement Task 1264 Configuration information. The report starts with the timestamp of 1265 the report generation on the MA and details about the MA including 1266 the optional Measurement Agent ID and Group ID (controlled by the 1267 Configuration Information). 1269 Much of the report Information is optional and will depend on the 1270 implementation of the Reporting Task and any parameters defined in 1271 the Task Configuration for the Reporting Task. For example some 1272 Reporting Tasks may choose not to include the Measurement Task 1273 Configuration or Action parameters, while others may do so dependent 1274 on the Controller setting a configurable parameter in the Task 1275 Configuration. 1277 It is possible for a Reporting Task to send just the Report header 1278 (datetime and optional agent ID and/or Group ID) if no measurement 1279 data is available. Whether to send such empty reports again is 1280 dependent on the implementation of the Reporting Task and potential 1281 Task Configuration parameter. 1283 The handling of measurement data on the MA before generating a Report 1284 and transfer from the MA to the Collector is dependent on the 1285 implementation of the device, MA and/or scheduled Tasks and not 1286 defined by the LMAP standards. Such decisions may include limits to 1287 the measurement data storage and what to do when such available 1288 storage becomes depleted. It is generally suggested that 1289 implementations running out of storage stop executing new measurement 1290 tasks and retain old measurement data. 1292 No context information, such as line speed or broadband product are 1293 included within the report header information as this data is 1294 reported by individual tasks at the time they execute. Either a 1295 Measurement Task can report contextual parameters that are relevant 1296 to that particular measurement, or specific tasks can be used to 1297 gather a set of contextual and environmental data at certain times 1298 independent of the reporting schedule. 1300 After the report header information the results are reported grouped 1301 according to different Measurement Task Configurations. Each Task 1302 section optionally starts with replicating the Measurement Task 1303 Configuration information before the result headers (titles for data 1304 columns) and the result data rows. The Options reported are those 1305 used for the scheduled execution of the Measurement Task and 1306 therefore include the Options specified in the Task Configuration as 1307 well as additional Options specified in the Action. The Action 1308 Options are appended to the Task Configuration Options in exactly the 1309 same order as they were provided to the Task during execution. 1311 The result row data includes a time for the start of the measurement 1312 and optionally an end time where the duration also needs to be 1313 considered in the data analysis. 1315 Some Measurement Tasks may optionally include an indication of the 1316 cross-traffic although the definition of cross-traffic is left up to 1317 each individual Measurement Task. Some Measurement Tasks may also 1318 output other environmental measures in addition to cross-traffic such 1319 as CPU utlilisation or interface speed. 1321 Whereas the Configuration and Instruction information represent 1322 information transmitted via the Control Protocol, the Report 1323 represents the information that is transmitted via the Report 1324 Protocol. It is constructed at the time of sending a report and 1325 represents the inherent structure of the information that is sent to 1326 the Collector. 1328 3.6.1. Definition of ma-report-obj 1330 object { 1331 datetime ma-report-date; 1332 [uuid ma-report-agent-id;] 1333 [string ma-report-group-id;] 1334 [string ma-report-measurement-point;] 1335 [ma-report-result-obj ma-report-results<0..*>;] 1336 } ma-report-obj; 1338 The ma-report-obj provides the meta-data of a single report and 1339 consists of the following elements: 1341 ma-report-date: The date and time when the report was 1342 sent to a collector. 1344 ma-report-agent-id: An optional uuid uniquely identifying 1345 the measurement agent. 1347 ma-report-group-id: An optional identifier of the group of 1348 measurement agents this measurement 1349 agent belongs to. 1351 ma-report-measurement-point: An optional identifier for the 1352 measurement point indicating where the 1353 measurement agent is located on a path 1354 (see [RFC7398] for further details). 1356 ma-report-results: An optional and possibly empty 1357 unordered set of result objects. 1359 3.6.2. Definition of ma-report-result-obj 1360 object { 1361 string ma-report-result-schedule-name; 1362 string ma-report-result-action-name; 1363 string ma-report-result-task-name; 1364 [ma-option-obj ma-report-result-options<0..*>;] 1365 [string ma-report-result-tags<0..*>;] 1366 datetime ma-report-result-event-time; 1367 datetime ma-report-result-start-time; 1368 [datetime ma-report-result-end-time;] 1369 [string ma-report-result-cycle-number;] 1370 int ma-report-result-status; 1371 [ma-report-conflict-obj ma-report-result-conflicts<0..*>;] 1372 [ma-report-table-obj ma-report-result-tables<0..*>;] 1373 } ma-report-result-obj; 1375 The ma-report-result-obj provides the meta-data of a result report of 1376 a single executed action. It consists of the following elements: 1378 ma-report-result-schedule-name: The name of the schedule that 1379 produced the result. 1381 ma-report-result-action-name: The name of the action in the 1382 schedule that produced the result. 1384 ma-report-result-task-name: The name of the task that produced 1385 the result. 1387 ma-report-result-options: An optional ordered joined list of 1388 options provided by the task object 1389 and the action object when the action 1390 was started. 1392 ma-report-result-tags: An optional unordered set of tags. 1393 This is the joined set of tags 1394 provided by the task object and the 1395 action object and schedule object 1396 when the action was started. 1398 ma-report-result-event-time: The date and time of the event that 1399 triggered the schedule of the action 1400 that produced the reported result 1401 values. The date and time does not 1402 include any added randomization. 1404 ma-report-result-start-time: The date and time of the start of the 1405 action that produced the reported 1406 result values. 1408 ma-report-result-end-time: An optional date and time indicating 1409 when the action finished. 1411 ma-report-result-cycle-number: An optional cycle number derived from 1412 ma-report-result-event-time. It is 1413 the time closest to ma-report-result- 1414 event-time that is a multiple of the 1415 ma-event-cycle-interval of the event 1416 that triggered the execution of the 1417 schedule. The value is only present 1418 in an ma-report-result-obj if the 1419 event that triggered the execution of 1420 the schedule has a defined ma-event- 1421 cycle-interval. The cycle number is 1422 represented in the format 1423 YYYYMMDD.HHMMSS where YYYY represents 1424 the year, MM the month (1..12), DD 1425 the day of the months (01..31), HH 1426 the hour (00..23), MM the minute 1427 (00..59), and SS the second (00..59). 1428 The cycle number is using Coordinated 1429 Universal Time (UTC). 1431 ma-report-result-status: The status code returned by the 1432 execution of the action. 1434 ma-report-result-conflicts: A possibly empty set of conflict 1435 actions that might have impacted the 1436 measurement results being reported. 1438 ma-report-result-tables: An optional and possibly empty 1439 unordered set of result tables. 1441 3.6.3. Definition of ma-report-conflict-obj 1443 object { 1444 string ma-report-conflict-schedule-name; 1445 string ma-report-conflict-action-name; 1446 string ma-report-conflict-task-name; 1447 } ma-report-conflict-obj; 1449 The ma-report-conflict-obj provides the information about conflicting 1450 action that might have impacted the measurement results. It consists 1451 of the following elements: 1453 ma-report-result-schedule-name: The name of the schedule that may 1454 have impacted the result. 1456 ma-report-result-action-name: The name of the action in the 1457 schedule that may have impacted the 1458 result. 1460 ma-report-result-task-name: The name of the task that may have 1461 impacted the result. 1463 3.6.4. Definition of ma-report-table-obj 1465 object { 1466 [ma-registry-obj ma-report-table-functions<0..*>;] 1467 [string] ma-report-table-column-labels<0..*>;] 1468 [ma-report-row-obj ma-report-table-rows<0..*>;] 1469 } ma-report-table-obj; 1471 The ma-report-table-obj represents a result table and consists of the 1472 following elements: 1474 ma-report-table-functions: An optional and possibly empty 1475 unordered set of registry entries 1476 identifying the functions for which 1477 results that are reported. 1479 ma-report-table-column-labels: An optional and possibly empty 1480 ordered list of column labels. 1482 ma-report-table-rows: A possibly empty ordered list of 1483 result rows. 1485 3.6.5. Definition of ma-report-row-obj 1487 object { 1488 data ma-report-row-values<0..*>; 1489 } ma-report-row-obj; 1491 The ma-report-row-obj represents a result row and consists of the 1492 following elements: 1494 ma-report-row-values: A possibly empty ordered list of result 1495 values. When present, it contains an 1496 ordered list of values that align to the 1497 set of column labels for the report. 1499 3.7. Common Objects: Schedules 1501 A Schedule specifies the execution of a single or repeated series of 1502 Actions. An Action extends a Configured Task with additional 1503 specific parameters. Each Schedule contains basically two elements: 1505 an ordered list of Actions to be executed and an Event object 1506 triggering the execution of the Schedule. The Schedule states what 1507 Actions to run (with what configuration) and when to run the Actions. 1508 A Schedule may optionally have an Event that stops the execution of 1509 the Schedule or a maximum duration after which a schedule is stopped. 1511 Multiple Actions contained as an ordered list of a single Measurement 1512 Schedule will be executed according to the execution mode of the 1513 Schedule. In sequential mode, Actions will be executed sequentially 1514 and in parallel mode, all Actions will be executed concurrently. In 1515 pipelined mode, data produced by one Action is passed to the 1516 subsequent Action. Actions contained in different Schedules execute 1517 in parallel with such conflicts being reported in the Reporting 1518 Information where necessary. If two or more Schedules have the same 1519 start time, then the two will execute in parallel. There is no 1520 mechanism to prioritise one schedule over another or to mutex 1521 scheduled tasks. 1523 As well as specifying which Actions to execute, the Schedule also 1524 specifies how to link the data outputs from each Action to other 1525 Schedules. Specifying this within the Schedule allows the highest 1526 level of flexibility since it is even possible to send the output 1527 from different executions of the same Task Configuration to different 1528 destinations. A single Task producing multiple different outputs is 1529 expected to properly tag the different result. An Action receiving 1530 the output can then filter the results based on the tag if necessary. 1531 For example, a Measurement Task might report routine results to a 1532 data Reporting Task in a Schedule that communicates hourly via the 1533 Broadband PPP interface, but also outputs emergency conditions via an 1534 alarm Reporting Task in a different Schedule communicating 1535 immediately over a GPRS channel. Note that task-to-task data 1536 transfer is always specified in association with the scheduled 1537 execution of the sending task - there is no need for a corresponding 1538 input specification for the receiving task. While it is likely that 1539 an MA implementation will use a queue mechanism between the Schedules 1540 or Actions, this Information Model does not mandate or define a 1541 queue. The Information Model, however, reports the storage allocated 1542 to Schedules and Actions so that storage usage can be monitored. 1543 Furthermore, it is recommended that MA implementations by default 1544 retain old data and stop the execution of new measurement tasks if 1545 the MA runs out of storage capacity. 1547 When specifying the task to execute within the Schedule, i.e., 1548 creating an Action, it is possible to add to the Action option 1549 parameters. This allows the Task Configuration to determine the 1550 common characteristics of a Task, while selected parameters (e.g., 1551 the test target URL) are defined within as option parameters of the 1552 Action in the schedule. A single Tasks Configuration can even be 1553 used multiple times in the same schedule with different additional 1554 parameters. This allows for efficiency in creating and transferring 1555 the Instruction. Note that the semantics of what happens if an 1556 option is defined multiple times (either in the Task Configuration, 1557 Action or in both) is not standardised and will depend upon the Task. 1558 For example, some tasks may legitimately take multiple values for a 1559 single parameter. 1561 Where Options are specified in both the Action and the Task 1562 Configuration, the Action Options are appended to those specified in 1563 the Task Configuration. 1565 Example: An Action of a Schedule references a single Measurement 1566 Task Configuration for measuring UDP latency. It specifies that 1567 results are to be sent to a Schedule with a Reporting Action. 1568 This Reporting Task of the Reporting Action is executed by a 1569 separate Schedule that specifies that it should run hourly at 5 1570 minutes past the hour. When run this Reporting Action takes the 1571 data generated by the UDP latency Measurement Task as well as any 1572 other data to be included in the hourly report and transfers it to 1573 the Collector over the Report Channel specified within its own 1574 Schedule. 1576 Schedules and Actions may optionally also be given tags that are 1577 included in result reports sent to a Collector. In addition, 1578 schedules can be given suppression tags that may be used to select 1579 Schedules and Actions for suppression. 1581 3.7.1. Definition of ma-schedule-obj 1583 object { 1584 string ma-schedule-name; 1585 ma-event-obj ma-schedule-start; 1586 [ma-event-obj ma-schedule-end;] 1587 [int ma-schedule-duration;] 1588 ma-action-obj ma-schedule-actions<0..*>; 1589 string ma-schedule-execution-mode; 1590 [string ma-schedule-tags<0..*>;] 1591 [string ma-schedule-suppression-tags<0..*>;] 1592 } ma-schedule-obj; 1594 The ma-schedule-obj is the main scheduling object. It consists of 1595 the following elements: 1597 ma-schedule-name: A name uniquely identifying a 1598 scheduling object. 1600 ma-schedule-start: An event object indicating when the 1601 schedule starts. 1603 ma-schedule-end: An optional event object controlling 1604 the forceful termination of scheduled 1605 actions. When the event occurs, all 1606 actions of the schedule will be forced 1607 to terminate gracefully. 1609 ma-schedule-duration: An optional duration in seconds for the 1610 schedule. All actions of the schedule 1611 will be forced to terminate gracefully 1612 after the duration number of seconds 1613 past the start of the schedule. 1615 ma-schedule-actions: A possibly empty ordered list of 1616 actions to invoke when the schedule 1617 starts. 1619 ma-schedule-execution-mode: Indicates whether the actions should be 1620 executed sequentially, in parallel, or 1621 in a pipelined mode (where data 1622 produced by one action is passed to the 1623 subsequent action). The default 1624 execution mode is pipelined. 1626 ma-schedule-tags: An optional unordered set of tags that 1627 are reported together with the 1628 measurement results to a collector. 1630 ma-schedule-suppression-tags: An optional unordered set of 1631 suppression tags that are used to 1632 select schedules to be suppressed. 1634 3.7.2. Definition of ma-action-obj 1636 object { 1637 string ma-action-name; 1638 string ma-action-config-task-name; 1639 [ma-option-obj ma-action-task-options<0..*>;] 1640 [string ma-action-destinations<0..*>;] 1641 [string ma-action-tags<0..*>;] 1642 [string ma-action-suppression-tags<0..*>;] 1643 } ma-action-obj; 1645 The ma-action-obj models a task together with its schedule specific 1646 task options and destination schedules. It consists of the following 1647 elements: 1649 ma-action-name: A name uniquely identifying an action 1650 of a scheduling object. 1652 ma-action-config-task-name: A name identifying the configured task 1653 to be invoked by the action. 1655 ma-action-task-options: An optional and possibly empty ordered 1656 list of options (name-value pairs) that 1657 are passed to the task by appending 1658 them to the options configured for the 1659 task object. 1661 ma-action-destinations: An optional and possibly empty 1662 unordered set of names of destination 1663 schedules that consume output produced 1664 by this action. 1666 ma-action-tags: An optional unordered set of tags that 1667 are reported together with the 1668 measurement results to a collector. 1670 ma-action-suppression-tags: An optional unordered set of 1671 suppression tags that are used to 1672 select actions to be suppressed. 1674 3.8. Common Objects: Channels 1676 A Channel defines a bi-directional communication mechanism between 1677 the MA and a Controller or Collector. Multiple Channels can be 1678 defined to enable results to be split or duplicated across different 1679 Collectors. 1681 Each Channel contains the details of the remote endpoint (including 1682 location and security credential information such as a certificate). 1683 The timing of when to communicate over a Channel is specified by the 1684 Schedule which executes the corresponding Control or Reporting Task. 1685 The certificate can be the digital certificate associated to the FQDN 1686 in the URL or it can be the certificate of the Certification 1687 Authority that was used to issue the certificate for the FQDN (Fully 1688 Qualified Domain Name) of the target URL (which will be retrieved 1689 later on using a communication protocol such as TLS). In order to 1690 establish a secure channel, the MA will use its own security 1691 credentials (in the Configuration Information) and the given 1692 credentials for the individual Channel end-point. 1694 As with the Task Configurations, each Channel is also given a text 1695 name by which it can be referenced as a Task Option. 1697 Although the same in terms of information, Channels used for 1698 communication with the Controller are referred to as Control Channels 1699 whereas Channels to Collectors are referred to as Report Channels. 1700 Hence Control Channels will be referenced from Control Tasks executed 1701 by a Control Schedule, whereas Report Channels will be referenced 1702 from within Reporting Tasks executed by an Instruction Schedule. 1704 Multiple interfaces are also supported. For example the Reporting 1705 Task could be configured to send some results over GPRS. This is 1706 especially useful when such results indicate the loss of connectivity 1707 on a different network interface. 1709 Example: A Channel used for reporting results may specify that 1710 results are to be sent to the URL (https://collector.example.org/ 1711 report/), using the appropriate digital certificate to establish a 1712 secure channel. 1714 3.8.1. Definition of ma-channel-obj 1716 object { 1717 string ma-channel-name; 1718 url ma-channel-target; 1719 credentials ma-channel-credentials; 1720 [string ma-channel-interface-name;] 1721 } ma-channel-obj; 1723 The ma-channel-obj consists of the following elements: 1725 ma-channel-name: A unique name identifying the channel 1726 object. 1728 ma-channel-target: A URL identifying the target channel 1729 endpoint. 1731 ma-channel-credentials: The security credentials needed to 1732 establish a secure channel. 1734 ma-channel-interface-name: An optional name of the network interface 1735 to be used. If not present, the IP 1736 protocol stack will select a suitable 1737 interface. 1739 3.9. Common Objects: Task Configurations 1741 Conceptually each Task Configuration defines the parameters of a Task 1742 that the Measurement Agent (MA) may perform at some point in time. 1743 It does not by itself actually instruct the MA to perform them at any 1744 particular time (this is done by a Schedule). Tasks can be 1745 Measurement Tasks (i.e., those Tasks actually performing some type of 1746 passive or active measurement) or any other scheduled activity 1747 performed by the MA such as transferring information to or from the 1748 Controller and Collectors. Other examples of Tasks may include data 1749 manipulation or processing Tasks conducted on the MA. 1751 A Measurement Task Configuration is the same in information terms to 1752 any other Task Configuration. Both measurement and non-measurement 1753 Tasks may have registry entries to enable the MA to uniquely identify 1754 the Task it should execute and retrieve the schema for any parameters 1755 that may be passed to the Task. Registry entries are specified as a 1756 URI and can therefore be used to identify the Task within a namespace 1757 or point to a web or local file location for the Task information. 1758 As mentioned previously, these URIs may be used to identify the 1759 Measurement Task in a public namespace 1760 [I-D.ietf-ippm-metric-registry]. 1762 Example: A Measurement Task Configuration may configure a single 1763 Measurement Task for measuring UDP latency. The Measurement Task 1764 Configuration could define the destination port and address for 1765 the measurement as well as the duration, internal packet timing 1766 strategy and other parameters (for example a stream for one hour 1767 and sending one packet every 500 ms). It may also define the 1768 output type and possible parameters (for example the output type 1769 can be the 95th percentile mean) where the measurement task 1770 accepts such parameters. It does not define when the task starts 1771 (this is defined by the Schedule element), so it does not by 1772 itself instruct the MA to actually perform this Measurement Task. 1774 The Task Configuration will include a local short name for reference 1775 by a Schedule. Task Configurations may also refer to registry 1776 entries as described above. In addition the Task can be configured 1777 through a set of configuration Options. The nature and number of 1778 these Options will depend upon the Task. These options are expressed 1779 as name-value pairs although the 'value' may be a structured object 1780 instead of a simple string or numeric value. The implementation of 1781 these name-value pairs will vary between data models. 1783 An Option that must be present for Reporting Tasks is the Channel 1784 reference specifying how to communicate with a Collector. This is 1785 included in the task options and will have a value that matches a 1786 channel name that has been defined in the Instruction. Similarly 1787 Control Tasks will have a similar option with the value set to a 1788 specified Control Channel. 1790 A Reporting Task might also have a flag parameter, defined as an 1791 Option, to indicate whether to send a report without measurement 1792 results if there is no measurement result data pending to be 1793 transferred to the Collector. In addition many tasks will also take 1794 as a parameter which interface to operate over. 1796 In addition the Task Configuration may optionally also be given tags 1797 that can carry a Measurement Cycle ID. The purpose of this ID is to 1798 easily identify a set of measurement results that have been produced 1799 by Measurement Tasks with comparable Options. This ID could be 1800 manually incremented or otherwise changed when an Option change is 1801 implemented which could mean that two sets of results should not be 1802 directly compared. 1804 3.9.1. Definition of ma-task-obj 1806 object { 1807 string ma-task-name; 1808 ma-registry-obj ma-task-functions<0..*>; 1809 [ma-option-obj ma-task-options<0..*>;] 1810 [string ma-task-tags<0..*>;] 1811 } ma-task-obj; 1813 The ma-task-obj defines a configured task that can be invoked as part 1814 of an action. A configured task can be referenced by its name and it 1815 contains a possibly empty set of URIs to link to registry entries. 1816 Options allow the configuration of task parameters (in the form of 1817 name-value pairs). The ma-task-obj consists of the following 1818 elements: 1820 ma-task-name: A name uniquely identifying a configured 1821 task object. 1823 ma-task-functions: A possibly empty unordered set of registry 1824 entries identifying the functions of the 1825 configured task. 1827 ma-task-options: An optional and possibly empty ordered list 1828 of options (name-value pairs) that are 1829 passed to the configured task. 1831 ma-task-tags: An optional unordered set of tags that are 1832 reported together with the measurement 1833 results to a collector. 1835 3.9.2. Definition of ma-option-obj 1837 object { 1838 string ma-option-name; 1839 [object ma-option-value;] 1840 } ma-option-obj; 1842 The ma-option-obj models a name-value pair and consists of the 1843 following elements: 1845 ma-option-name: The name of the option. 1847 ma-option-value: The optional value of the option. 1849 The ma-option-obj is used to define Task Configuration Options. Task 1850 Configuration Options are generally task specific. For tasks 1851 associated with an entry in a registry, the registry may define well- 1852 known option names (e.g., the so-called parameters in the IPPM metric 1853 registry [I-D.ietf-ippm-metric-registry]). Control and Reporting 1854 Tasks need to know the Channel they are going to use. The common 1855 option name for specifying the channel is "channel" where the 1856 option's value refers to the name of an ma-channel-obj. 1858 3.10. Common Objects: Registry Information 1860 Tasks and actions can be associated with entries in a registry. A 1861 registry object refers to an entry in a registry (identified by a 1862 URI) and it may define a set of roles. 1864 3.10.1. Definition of ma-registry-obj 1866 object { 1867 uri ma-registry-uri; 1868 [string ma-registry-role<0..*>;] 1869 } ma-registry-obj; 1871 The ma-registry-obj refers to an entry of a registry and it defines 1872 the associated role(s). The ma-registry-obj consists of the 1873 following elements: 1875 ma-registry-uri: A URI identifying an entry in a registry. 1877 ma-registry-role: An optional and possibly empty unordered 1878 set of roles for the identified registry 1879 entry. 1881 3.11. Common Objects: Event Information 1883 The Event information object used throughout the information models 1884 can initially take one of several different forms. Additional forms 1885 may be defined later in order to bind the execution of schedules to 1886 additional events. The initially defined Event forms are: 1888 1. Periodic Timing: Emits multiple events periodically according to 1889 an interval time defined in seconds 1891 2. Calendar Timing: Emits multiple events according to a calendar 1892 based pattern, e.g., 22 minutes past each hour of the day on 1893 weekdays 1895 3. One Off Timing: Emits one event at a specific date and time 1897 4. Immediate: Emits one event as soon as possible 1899 5. Startup: Emits an event whenever the MA is started (e.g., at 1900 device startup) 1902 6. Controller Lost: Emits an event when connectivity to the 1903 controller has been lost 1905 7. Controller Connected: Emits an event when connectivity to the 1906 controller has been (re-)established 1908 Optionally each of the Event options may also specify a randomness 1909 that should be evaluated and applied separately to each indicated 1910 event. This randomness parameter defines a uniform interval in 1911 seconds over which the start of the task is delayed from the starting 1912 times specified by the event object. 1914 Both the Periodic and Calendar timing objects allow for a series of 1915 Actions to be executed. While both have an optional end time, it is 1916 best practice to always configure an end time and refresh the 1917 information periodically to ensure that lost MAs do not continue 1918 their tasks forever. 1920 Startup events are only created on device startup, not when a new 1921 Instruction is transferred to the MA. If scheduled task execution is 1922 desired both on the transfer of the Instruction and on device restart 1923 then both the Immediate and Startup timing needs to be used in 1924 conjunction. 1926 The datetime format used for all elements in the information model 1927 MUST conform to RFC 3339 [RFC3339]. 1929 3.11.1. Definition of ma-event-obj 1930 object { 1931 string ma-event-name; 1932 union { 1933 ma-periodic-obj ma-event-periodic; 1934 ma-calendar-obj ma-event-calendar; 1935 ma-one-off-obj ma-event-one-off; 1936 ma-immediate-obj ma-event-immediate; 1937 ma-startup-obj ma-event-startup; 1938 ma-controller-lost-obj ma-event-controller-lost; 1939 ma-controller-connected-obj ma-event-controller-connected; 1940 } 1941 [int ma-event-random-spread;] 1942 [int ma-event-cycle-interval;] 1943 } ma-event-obj; 1945 The ma-event-obj is the main event object. Event objects are 1946 identified by a name. A generic event object itself contains a more 1947 specific event object. The set of specific event objects should be 1948 extensible. The initial set of specific event objects is further 1949 described below. The ma-event-obj also includes an optional uniform 1950 random spread that can be used to randomize the start times of 1951 schedules triggered by an event. The ma-event-obj consists of the 1952 following elements: 1954 ma-event-name: The name uniquely identifies an event 1955 object. Schedules refer to event 1956 objects by this name. 1958 ma-event-periodic: The ma-event-periodic is present for 1959 periodic timing objects. 1961 ma-event-calendar: The ma-event-calendar is present for 1962 calendar timing objects. 1964 ma-event-one-off: The ma-event-one-off is present for 1965 one-off timing objects. 1967 ma-event-immediate: The ma-event-immediate is present for 1968 immediate event objects. 1970 ma-event-startup: The ma-event-startup is present for 1971 startup event objects. 1973 ma-event-controller-lost: The ma-event-controller-lost is 1974 present for connectivity to 1975 controller lost event objects. 1977 ma-event-controller-connected: The ma-event-controller-connected is 1978 present for connectivity to a 1979 controller established event objects. 1981 ma-event-random-spread: The optional ma-event-random-spread 1982 adds a random delay defined in 1983 seconds to the event object. No 1984 random delay is added if ma-event- 1985 random-spread does not exist. 1987 ma-event-cycle-interval: The optional ma-event-cycle-interval 1988 defines the duration of the time 1989 interval in seconds that is used to 1990 calculate cycle numbers. No cycle 1991 number is calculated if ma-event- 1992 cycle-interval does not exist. 1994 3.11.2. Definition of ma-periodic-obj 1996 object { 1997 [datetime ma-periodic-start;] 1998 [datetime ma-periodic-end;] 1999 int ma-periodic-interval; 2000 } ma-periodic-obj; 2002 The ma-periodic-obj timing object has an optional start and an 2003 optional end time plus a periodic interval. Schedules using an ma- 2004 periodic-obj are started periodically between the start and end time. 2005 The ma-periodic-obj consists of the following elements: 2007 ma-periodic-start: The optional date and time at which 2008 Schedules using this object are first 2009 started. If not present it defaults to 2010 immediate. 2012 ma-periodic-end: The optional date and time at which 2013 Schedules using this object are last 2014 started. If not present it defaults to 2015 indefinite. 2017 ma-periodic-interval: The interval defines the time in seconds 2018 between two consecutive starts of tasks. 2020 3.11.3. Definition of ma-calendar-obj 2022 Calendar Timing supports the routine execution of Schedules at 2023 specific times and/or on specific dates. It can support more 2024 flexible timing than Periodic Timing since the execution of Schedules 2025 does not have to be uniformly spaced. For example a Calendar Timing 2026 could support the execution of a Measurement Task every hour between 2027 6pm and midnight on weekdays only. 2029 Calendar Timing is also required to perform measurements at 2030 meaningful times in relation to network usage (e.g., at peak times). 2031 If the optional timezone offset is not supplied then local system 2032 time is assumed. This is essential in some use cases to ensure 2033 consistent peak-time measurements as well as supporting MA devices 2034 that may be in an unknown timezone or roam between different 2035 timezones (but know their own timezone information such as through 2036 the mobile network). 2038 The calendar elements within the Calendar Timing do not have defaults 2039 in order to avoid accidental high-frequency execution of Tasks. If 2040 all possible values for an element are desired then the wildcard * is 2041 used. 2043 object { 2044 [datetime ma-calendar-start;] 2045 [datetime ma-calendar-end;] 2046 [string ma-calendar-months<0..*>;] 2047 [string ma-calendar-days-of-week<0..*>;] 2048 [string ma-calendar-days-of-month<0..*>;] 2049 [string ma-calendar-hours<0..*>;] 2050 [string ma-calendar-minutes<0..*>;] 2051 [string ma-calendar-seconds<0..*>;] 2052 [int ma-calendar-timezone-offset;] 2053 } ma-calendar-obj; 2055 ma-calendar-start: The optional date and time at which 2056 Schedules using this object are first 2057 started. If not present it defaults to 2058 immediate. 2060 ma-calendar-end: The optional date and time at which 2061 Schedules using this object are last 2062 started. If not present it defaults to 2063 indefinite. 2065 ma-calendar-months: The optional set of months (1-12) on 2066 which tasks scheduled using this object 2067 are started. The wildcard * means all 2068 months. If not present, it defaults to 2069 no months. 2071 ma-calendar-days-of-week: The optional set of days of a week 2072 ("Mon", "Tue", "Wed", "Thu", "Fri", 2073 "Sat", "Sun") on which tasks scheduled 2074 using this object are started. The 2075 wildcard * means all days of the week. 2076 If not present, it defaults to no days. 2078 ma-calendar-days-of-month: The optional set of days of a months 2079 (1-31) on which tasks scheduled using 2080 this object are started. The wildcard 2081 * means all days of a months. If not 2082 present, it defaults to no days. 2084 ma-calendar-hours: The optional set of hours (0-23) on 2085 which tasks scheduled using this object 2086 are started. The wildcard * means all 2087 hours of a day. If not present, it 2088 defaults to no hours. 2090 ma-calendar-minutes: The optional set of minutes (0-59) on 2091 which tasks scheduled using this object 2092 are started. The wildcard * means all 2093 minutes of an hour. If not present, it 2094 defaults to no hours. 2096 ma-calendar-seconds: The optional set of seconds (0-59) on 2097 which tasks scheduled using this object 2098 are started. The wildcard * means all 2099 seconds of an hour. If not present, it 2100 defaults to no seconds. 2102 ma-calendar-timezone-offset: The optional timezone offest in hours. 2103 If not present, it defaults to the 2104 system's local timezone. 2106 If a day of the month is specified that does not exist in the month 2107 (e.g., 29th of Feburary) then those values are ignored. 2109 3.11.4. Definition of ma-one-off-obj 2111 object { 2112 datetime ma-one-off-time; 2113 } ma-one-off-obj; 2115 The ma-one-off-obj timing object specifies a fixed point in time. 2116 Schedules using an ma-one-off-obj are started once at the specified 2117 date and time. The ma-one-off-obj consists of the following 2118 elements: 2120 ma-one-off-time: The date and time at which Schedules using 2121 this object are started. 2123 3.11.5. Definition of ma-immediate-obj 2125 object { 2126 // empty 2127 } ma-immediate-obj; 2129 The ma-immediate-obj event object has no further information 2130 elements. Schedules using an ma-immediate-obj are started as soon as 2131 possible. 2133 3.11.6. Definition of ma-startup-obj 2135 object { 2136 // empty 2137 } ma-startup-obj; 2139 The ma-startup-obj event object has no further information elements. 2140 Schedules or suppressions using an ma-startup-obj are started at MA 2141 initialization time. 2143 3.11.7. Definition of ma-controller-lost-obj 2145 object { 2146 // empty 2147 } ma-controller-lost-obj; 2149 The ma-controller-lost-obj event object has no further information 2150 elements. The ma-controller-lost-obj indicates that connectivity to 2151 the controller has been lost. This is determined by a timer started 2152 after each successful contact with a controller. When the timer 2153 reaches the controller-timeout (measured in seconds), an ma- 2154 controller-lost-obj event is generated. This event may be used to 2155 start a suppression. 2157 3.11.8. Definition of ma-controller-connected-obj 2159 object { 2160 // empty 2161 } ma-controller-connected-obj; 2163 The ma-controller-connected-obj event object has no further 2164 information elements. The ma-controller-connected-obj indicates that 2165 connectivity to the controller has been established again after it 2166 was lost. This event may be used to end a suppression. 2168 4. Example Execution 2170 The example execution has two event sources E1 and E2 and three 2171 schedules S1, S2, and S3. The schedule S3 is started by events of 2172 event source E2 while the schedules S1 and S2 are both started by 2173 events of the event source E1. The schedules S1 and S2 have two 2174 actions each and schedule S3 has a single action. The event source 2175 E2 has no randomization while the event source E1 has the 2176 randomization r. 2178 Figure 2 shows a possible timeline of an execution. The time T is 2179 progressing downwards. The dotted vertial line indicates progress of 2180 time while a dotted horizontal line indicates which schedule are 2181 triggered by an event. Tilded lines indicate data flowing from an 2182 action to another schedule. Actions within a schedule are named A1, 2183 A2, etc. 2185 E2 E1 T S1 S2 S3 2186 sequential parallel pipelined 2187 : 2188 e0 + 2189 : 2190 : 2191 e0+r + .......... + .......... ++ 2192 : | A1 A1 || A2 2193 : + |+ ~~~~~~~> 2194 : | A2 | 2195 : | + ~~~~~~~~> 2196 : + ~~~~~~~~~~~~~~~~~~~~~> 2197 : 2198 : 2199 e1 + 2200 : 2201 e1+r + .......... + .......... ++ 2202 : | A1 A1 || 2203 : | +|~~~~~~~> 2204 : | | A2 2205 : + +~~~~~~~> 2206 : | A2 2207 : + ~~~~~~~~~~~~~~~~~~~~> 2208 e0 + ................................... + 2209 : | A1 2210 e3 + | 2211 e3+r + .......... + .......... ++ | 2212 : | A1 A1 || A2 | 2213 : + ++ ~~~~~~> | 2214 : | A2 + 2215 : + ~~~~~~~~~~~~~~~~~~~~> 2216 V 2218 Figure 2: Example Execution 2220 Note that implementations must handle possible concurrency issues. 2221 In the example execution, action A1 of schedule S3 is consuming the 2222 data that has been forwarded to schedule S3 while additional data is 2223 arriving from action A2 of schedule S2. 2225 5. IANA Considerations 2227 This document makes no request of IANA. 2229 Note to the RFC Editor: this section may be removed on publication as 2230 an RFC. 2232 6. Security Considerations 2234 This Information Model deals with information about the control and 2235 reporting of the Measurement Agent. There are broadly two security 2236 considerations for such an Information Model. Firstly the 2237 Information Model has to be sufficient to establish secure 2238 communication channels to the Controller and Collector such that 2239 other information can be sent and received securely. Additionally, 2240 any mechanisms that the Network Operator or other device 2241 administrator employs to pre-configure the MA must also be secure to 2242 protect unauthorized parties from modifying pre-configuration 2243 information. These mechanisms are important to ensure that the MA 2244 cannot be hijacked, for example to participate in a distributed 2245 denial of service attack. 2247 The second consideration is that no mandated information items should 2248 pose a risk to confidentiality or privacy given such secure 2249 communication channels. For this latter reason items such as the MA 2250 context and MA ID are left optional and can be excluded from some 2251 deployments. This may, for example, allow the MA to remain anonymous 2252 and for information about location or other context that might be 2253 used to identify or track the MA to be omitted or blurred. 2254 Implementations and deployments should also be careful about exposing 2255 device-ids when this is not strictly needed. 2257 An implementation of this Information Model should support all the 2258 security and privacy requirements associated with the LMAP Framework 2259 [RFC7594]. In addition, users of this Information Model are advised 2260 to choose identifiers for Group IDs, tags or names of information 2261 model objects (e.g., configured tasks, schedules or actions) that do 2262 not reveal any sensitive information to people authorized to process 2263 measurement results but who are not authorized to know details about 2264 the Measurement Agents that were used to perform the measurement. 2266 7. Acknowledgements 2268 Several people contributed to this specification by reviewing early 2269 versions and actively participating in the LMAP working group 2270 (apologies to those unintentionally omitted): Vaibhav Bajpai, Michael 2271 Bugenhagen, Timothy Carey, Alissa Cooper, Kenneth Ko, Al Morton, Dan 2272 Romascanu, Henning Schulzrinne, Andrea Soppera, Barbara Stark, and 2273 Jason Weil. 2275 Trevor Burbridge, Philip Eardley, Marcelo Bagnulo and Juergen 2276 Schoenwaelder worked in part on the Leone research project, which 2277 received funding from the European Union Seventh Framework Programme 2278 [FP7/2007-2013] under grant agreement number 317647. 2280 Juergen Schoenwaelder was partly funded by Flamingo, a Network of 2281 Excellence project (ICT-318488) supported by the European Commission 2282 under its Seventh Framework Programme. 2284 8. References 2286 8.1. Normative References 2288 [ISO.10646] 2289 International Organization for Standardization, 2290 "Information Technology - Universal Multiple-Octet Coded 2291 Character Set (UCS)", ISO Standard 10646:2014, 2014. 2293 [POSIX.2] The IEEE and The Open Group, "The Open Group Base 2294 Specifications Issue 7", IEEE Standard 1003.1-2008, 2016. 2296 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2297 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 2298 RFC2119, March 1997, 2299 . 2301 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 2302 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 2303 . 2305 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2306 Resource Identifier (URI): Generic Syntax", STD 66, RFC 2307 3986, DOI 10.17487/RFC3986, January 2005, 2308 . 2310 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 2311 Unique IDentifier (UUID) URN Namespace", RFC 4122, DOI 10 2312 .17487/RFC4122, July 2005, 2313 . 2315 8.2. Informative References 2317 [I-D.ietf-ippm-metric-registry] 2318 Bagnulo, M., Claise, B., Eardley, P., Morton, A., and A. 2319 Akhter, "Registry for Performance Metrics", draft-ietf- 2320 ippm-metric-registry-10 (work in progress), November 2016. 2322 [I-D.ietf-lmap-yang] 2323 Schoenwaelder, J. and V. Bajpai, "A YANG Data Model for 2324 LMAP Measurement Agents", draft-ietf-lmap-yang-10 (work in 2325 progress), January 2017. 2327 [RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between 2328 Information Models and Data Models", RFC 3444, DOI 10 2329 .17487/RFC3444, January 2003, 2330 . 2332 [RFC7398] Bagnulo, M., Burbridge, T., Crawford, S., Eardley, P., and 2333 A. Morton, "A Reference Path and Measurement Points for 2334 Large-Scale Measurement of Broadband Performance", RFC 2335 7398, DOI 10.17487/RFC7398, February 2015, 2336 . 2338 [RFC7536] Linsner, M., Eardley, P., Burbridge, T., and F. Sorensen, 2339 "Large-Scale Broadband Measurement Use Cases", RFC 7536, 2340 DOI 10.17487/RFC7536, May 2015, 2341 . 2343 [RFC7594] Eardley, P., Morton, A., Bagnulo, M., Burbridge, T., 2344 Aitken, P., and A. Akhter, "A Framework for Large-Scale 2345 Measurement of Broadband Performance (LMAP)", RFC 7594, 2346 DOI 10.17487/RFC7594, September 2015, 2347 . 2349 Appendix A. Change History 2351 Note to the RFC Editor: this section should be removed on publication 2352 as an RFC. 2354 A.1. Non-editorial changes since -17 2356 o The information model is subdivided into aspects and not sections. 2358 o Changes to address the GEN-ART review comments. 2360 A.2. Non-editorial changes since -16 2362 o Addressing Alissa Cooper's review comments. 2364 A.3. Non-editorial changes since -15 2366 o The reference to the framework is now informational. 2368 A.4. Non-editorial changes since -14 2370 o Clarified that the cycle number is in UTC. 2372 A.5. Non-editorial changes since -13 2374 o Removed the ma-config-device-id from the ma-config-obj. 2376 o Added ma-config-report-group-id and clarified how two flags ma- 2377 config-report-agent-id and ma-config-report-group-id work. 2379 A.6. Non-editorial changes since -12 2381 o Renamed the ma-metrics-registry-obj to ma-registry-obj since tasks 2382 may refer to different registries (not just a metrics registry). 2384 o Clarifications and bug fixes. 2386 A.7. Non-editorial changes since -11 2388 o Clarifications and bug fixes. 2390 A.8. Non-editorial changes since -10 2392 o Rewrote the text concerning the well-known "channel" option name. 2394 o Added ma-report-result-event-time, ma-report-result-cycle-number, 2395 and ma-event-cycle-interval. 2397 o Added ma-capability-tags. 2399 o Added a new section showing an example execution. 2401 o Several clarifications and bug fixes. 2403 A.9. Non-editorial changes since -09 2405 o Added ma-status-schedule-storage and ma-status-action-storage. 2407 o Removed suppress-by-default. 2409 o Moved ma-report-result-metrics of the ma-report-result-obj to ma- 2410 report-table-metrics of the ma-report-table-obj so that the 2411 relationship between metrics and result tables is clear. 2413 o Added ma-report-conflict-obj. 2415 o Added ma-report-result-status to ma-report-result-obj. 2417 o Several clarifications and bug fixes. 2419 A.10. Non-editorial changes since -08 2421 o Refactored the ma-report-task-obj into the ma-report-result-obj. 2423 o Introduced the ma-report-table-obj so that a result can contain 2424 multiple tables. 2426 o Report schedule, action, and task name as part of the ma-report- 2427 result-obj. 2429 o Report conflicts per ma-report-result-obj and not per ma-report- 2430 row-obj. 2432 o Report the start/end time as part of the ma-report-result-obj. 2434 A.11. Non-editorial changes since -07 2436 o Added ma-schedule-end and ma-schedule-duration. 2438 o Changed the granularity of scheduler timings to seconds. 2440 o Added ma-status-suppression-obj to report the status of 2441 suppressions as done in the YANG data model. 2443 o Added counters to schedule and action status objects to match the 2444 counters in the YANG data model. 2446 o Using tags to pass information such as a measurement cycle 2447 identifier to the collector. 2449 o Using suppression tags and glob-style matching to select schedules 2450 and actions to be suppressed. 2452 A.12. Non-editorial changes since -06 2454 o The default execution mode is pipelined (LI12) 2456 o Added text to define which action consumes data in sequential, 2457 pipelines, and parallel execution mode (LI11) 2459 o Added ma-config-measurement-point, ma-report-measurement-point, 2460 and ma-config-report-measurement-point to configure and report the 2461 measurement point (LI10) 2463 o Turned ma-suppression-obj into a list that uses a start event and 2464 a stop event to define the start and end of suppression; this 2465 unifies the handling of suppression and loss of controller 2466 connectivity (LI09) 2468 o Added ma-controller-lost-obj and ma-controller-ok-obj event 2469 objects (LI09) 2471 o Added ma-status-schedule-obj to report the status of a schedule 2472 and refactored ma-task-status-obj into ma-status-action-obj to 2473 report the status of an action (LI07, LI08) 2475 o Introduced a common ma-metric-registry-obj that identifies a 2476 metric and a set of associated roles and added this object to 2477 expose metric capabilities and to support the configuration of 2478 metrics and to report the metrics used (LI06) 2480 o Introduced ma-capability-obj and ma-capability-task-obj to expose 2481 the capabilities of a measurement agent (LI05) 2483 o Use 'ordered list' or 'unordered set' instead of list, collection, 2484 etc. (LI02) 2486 o Clarification that Actions are part of a Schedule (LI03) 2488 o Deleted terms that are not strictly needed (LI04) 2490 A.13. Non-editorial changes since -05 2492 o A task can now reference multiply registry entries. 2494 o Consistent usage of the term Action and Task. 2496 o Schedules are triggered by Events instead of Timings; Timings are 2497 just one of many possible event sources. 2499 o Actions feed into other Schedules (instead of Actions within other 2500 Schedules). 2502 o Removed the notion of multiple task outputs. 2504 o Support for sequential, parallel, and pipelined execution of 2505 Actions. 2507 Authors' Addresses 2509 Trevor Burbridge 2510 BT 2511 Adastral Park, Martlesham Heath 2512 Ipswich IP5 3RE 2513 United Kingdom 2515 Email: trevor.burbridge@bt.com 2516 Philip Eardley 2517 BT 2518 Adastral Park, Martlesham Heath 2519 Ipswich IP5 3RE 2520 United Kingdom 2522 Email: philip.eardley@bt.com 2524 Marcelo Bagnulo 2525 Universidad Carlos III de Madrid 2526 Av. Universidad 30 2527 Leganes, Madrid 28911 2528 Spain 2530 Email: marcelo@it.uc3m.es 2532 Juergen Schoenwaelder 2533 Jacobs University Bremen 2534 Campus Ring 1 2535 Bremen 28759 2536 Germany 2538 Email: j.schoenwaelder@jacobs-university.de