idnits 2.17.1 draft-ietf-lmap-yang-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 15 instances of too long lines in the document, the longest one being 30 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 180 has weird spacing: '...nterval uin...' == Line 196 has weird spacing: '...rw time yan...' == Line 204 has weird spacing: '...nnected emp...' == Line 217 has weird spacing: '...started yan...' -- The document date (March 21, 2016) is 2957 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 (-18) exists of draft-ietf-lmap-information-model-08 -- Obsolete informational reference (is this intentional?): RFC 6536 (Obsoleted by RFC 8341) -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) Summary: 1 error (**), 0 flaws (~~), 6 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Schoenwaelder 3 Internet-Draft V. Bajpai 4 Intended status: Standards Track Jacobs University Bremen 5 Expires: September 22, 2016 March 21, 2016 7 A YANG Data Model for LMAP Measurement Agents 8 draft-ietf-lmap-yang-04.txt 10 Abstract 12 This document defines a data model for Large-Scale Measurement 13 Platforms (LMAP). The data model is defined using the YANG data 14 modeling language. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on September 22, 2016. 33 Copyright Notice 35 Copyright (c) 2016 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 51 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 2 52 1.2. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 3 53 2. Data Model Overview . . . . . . . . . . . . . . . . . . . . . 3 54 3. Relationship to the Information Model . . . . . . . . . . . . 7 55 4. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 8 56 5. Security Considerations . . . . . . . . . . . . . . . . . . . 41 57 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 43 58 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 44 59 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 45 60 8.1. Normative References . . . . . . . . . . . . . . . . . . 45 61 8.2. Informative References . . . . . . . . . . . . . . . . . 45 62 Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . 46 63 A.1. Purpose of /lmap-state/tasks . . . . . . . . . . . . . . 46 64 A.2. Streamline the reporting model . . . . . . . . . . . . . 46 65 A.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 46 66 Appendix B. Non-editorial Changes since -03 . . . . . . . . . . 47 67 Appendix C. Non-editorial Changes since -02 . . . . . . . . . . 47 68 Appendix D. Non-editorial Changes since -01 . . . . . . . . . . 47 69 Appendix E. Non-editorial Changes since -00 . . . . . . . . . . 48 70 Appendix F. Example IPPM Module for UDP Latency Metrics . . . . 48 71 Appendix G. Example Configuration (XML) . . . . . . . . . . . . 50 72 Appendix H. Example Configuration (JSON) . . . . . . . . . . . . 56 73 Appendix I. Example State (XML) . . . . . . . . . . . . . . . . 65 74 Appendix J. Example State (JSON) . . . . . . . . . . . . . . . . 67 75 Appendix K. Example Report (XML) . . . . . . . . . . . . . . . . 68 76 Appendix L. Example Report (JSON) . . . . . . . . . . . . . . . 70 77 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 72 79 1. Introduction 81 This document defines a data model for Large-Scale Measurement 82 Platforms (LMAP) [RFC7594]. The data model is defined using the YANG 83 [RFC6020] data modeling language. It aims to be consistent with the 84 LMAP Information Model [I-D.ietf-lmap-information-model]. 86 1.1. Terminology 88 This document uses the LMAP terminology defined in [RFC7594]. 90 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 91 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 92 document are to be interpreted as described in [RFC2119]. 94 1.2. Tree Diagrams 96 A simplified graphical representation of the data model is used in 97 this document. The meaning of the symbols in these diagrams is as 98 follows: 100 o Brackets "[" and "]" enclose list keys. 102 o Abbreviations before data node names: "rw" means configuration 103 (read-write), "ro" means state data (read-only), and "w" means RPC 104 input date (write-only). 106 o Symbols after data node names: "?" means an optional node, "!" 107 means a presence container, and "*" denotes a list and leaf-list. 109 o Parentheses enclose choice and case nodes, and case nodes are also 110 marked with a colon (":"). 112 o Ellipsis ("...") stands for contents of subtrees that are not 113 shown. 115 2. Data Model Overview 117 The tree diagram below shows the structure of the configuration data 118 model. 120 module: ietf-lmap-control 121 +--rw lmap 122 +--rw agent 123 | +--rw agent-id? yang:uuid 124 | +--rw device-id? inet:uri 125 | +--rw group-id? string 126 | +--rw measurement-point? string 127 | +--rw report-agent-id? boolean 128 | +--rw report-measurement-point? boolean 129 | +--rw controller-timeout? uint32 130 +--rw tasks 131 | +--rw task* [name] 132 | +--rw name lmap:identifier 133 | +--rw metric* [uri] 134 | | +--rw uri inet:uri 135 | | +--rw role* string 136 | +--rw program? string 137 | +--rw option* [id] 138 | | +--rw id lmap:identifier 139 | | +--rw name? string 140 | | +--rw value? string 141 | +--rw suppress-by-default? boolean 142 | +--rw tag* lmap:identifier 143 +--rw schedules 144 | +--rw schedule* [name] 145 | +--rw name lmap:identifier 146 | +--rw start event-ref 147 | +--rw (stop)? 148 | | +--:(end) 149 | | | +--rw end? event-ref 150 | | +--:(duration) 151 | | +--rw duration? uint32 152 | +--rw execution-mode? enumeration 153 | +--rw tag* lmap:tag 154 | +--rw suppression-tag* lmap:tag 155 | +--rw action* [name] 156 | +--rw name lmap:identifier 157 | +--rw task task-ref 158 | +--rw parameters 159 | | +--rw (extension)? 160 | +--rw option* [id] 161 | | +--rw id lmap:identifier 162 | | +--rw name? string 163 | | +--rw value? string 164 | +--rw destination* schedule-ref 165 | +--rw tag* lmap:tag 166 | +--rw suppression-tag* lmap:tag 167 +--rw suppressions 168 | +--rw suppression* [name] 169 | +--rw name lmap:identifier 170 | +--rw start? event-ref 171 | +--rw end? event-ref 172 | +--rw match* lmap:glob-pattern 173 | +--rw stop-running? boolean 174 +--rw events 175 +--rw event* [name] 176 +--rw name lmap:identifier 177 +--rw (event-type)? 178 | +--:(periodic) 179 | | +--rw periodic 180 | | +--rw interval uint32 181 | | +--rw start? yang:date-and-time 182 | | +--rw end? yang:date-and-time 183 | +--:(calendar) 184 | | +--rw calendar 185 | | +--rw month* lmap:month-or-all 186 | | +--rw day-of-month* lmap:day-of-months-or-all 187 | | +--rw day-of-week* lmap:weekday-or-all 188 | | +--rw hour* lmap:hour-or-all 189 | | +--rw minute* lmap:minute-or-all 190 | | +--rw second* lmap:second-or-all 191 | | +--rw timezone-offset? lmap:timezone-offset 192 | | +--rw start? yang:date-and-time 193 | | +--rw end? yang:date-and-time 194 | +--:(one-off) 195 | | +--rw one-off 196 | | +--rw time yang:date-and-time 197 | +--:(immediate) 198 | | +--rw immediate empty 199 | +--:(startup) 200 | | +--rw startup empty 201 | +--:(controller-lost) 202 | | +--rw controller-lost empty 203 | +--:(controller-connected) 204 | +--rw controller-connected empty 205 +--rw random-spread? uint32 207 The tree diagram below shows the structure of the state data model. 209 module: ietf-lmap-control 210 +--ro lmap-state 211 +--ro agent 212 | +--ro agent-id yang:uuid 213 | +--ro device-id inet:uri 214 | +--ro hardware string 215 | +--ro firmware string 216 | +--ro version string 217 | +--ro last-started yang:date-and-time 218 +--ro tasks 219 | +--ro task* [name] 220 | +--ro name lmap:identifier 221 | +--ro metric* [uri] 222 | | +--ro uri inet:uri 223 | | +--ro role* string 224 | +--ro version? string 225 | +--ro program? string 226 +--ro schedules 227 | +--ro schedule* [name] 228 | +--ro name lmap:identifier 229 | +--ro state? enumeration 230 | +--ro invocations? yang:counter32 231 | +--ro suppressions? yang:counter32 232 | +--ro overlaps? yang:counter32 233 | +--ro failures? yang:counter32 234 | +--ro last-invocation? yang:date-and-time 235 | +--ro action* [name] 236 | +--ro name lmap:identifier 237 | +--ro state? enumeration 238 | +--ro invocations? yang:counter32 239 | +--ro suppressions? yang:counter32 240 | +--ro overlaps? yang:counter32 241 | +--ro failures? yang:counter32 242 | +--ro last-invocation? yang:date-and-time 243 | +--ro last-completion? yang:date-and-time 244 | +--ro last-status? lmap:status-code 245 | +--ro last-message? string 246 | +--ro last-failed-completion? yang:date-and-time 247 | +--ro last-failed-status? lmap:status-code 248 | +--ro last-failed-message? string 249 +--ro suppressions 250 +--ro suppression* [name] 251 +--ro name lmap:identifier 252 +--ro state? enumeration 254 The tree diagram below shows the structure of the reporting data 255 model. 257 module: ietf-lmap-report 258 rpcs: 259 +---x report 260 +---w input 261 +---w date yang:date-and-time 262 +---w agent-id? yang:uuid 263 +---w group-id? string 264 +---w measurement-point? string 265 +---w result* 266 +---w schedule-name? lmap:identifier 267 +---w action-name? lmap:identifier 268 +---w task-name? lmap:identifier 269 +---w metric* [uri] 270 | +---w uri inet:uri 271 | +---w role* string 272 +---w option* [id] 273 | +---w id lmap:identifier 274 | +---w name? string 275 | +---w value? string 276 +---w tag* lmap:tag 277 +---w start yang:date-and-time 278 +---w end? yang:date-and-time 279 +---w conflict* lmap:identifier 280 +---w table* 281 +---w column* string 282 +---w row* 283 +---w value* string 285 3. Relationship to the Information Model 287 The LMAP information model [I-D.ietf-lmap-information-model] is 288 devided into six sections. They are mapped into the YANG data model 289 as explained below: 291 o Pre-Configuration Information: This is not modeled explicitly 292 since it is a subset of the configuration information. 294 o Configuration Information: This is modeled in the /lmap/agent 295 subtree, the /lmap/schedules subtree, and the /lmap/tasks subtree 296 described below. Some items have been left out because they are 297 expected to be dealt with by the underlying protocol. 299 o Instruction Information: This is modeled in the /lmap/suppressions 300 subtree, the /lmap/schedules subtree, and the /lmap/tasks subtree 301 described below. 303 o Logging Information: Some of the logging information, in 304 particular 'success/failure/warning messages in response to 305 information updates from the Controller', will be handled by the 306 protocol used to manipulate the lmap specific configuration. For 307 the first version of the LMAP data models, it is assumed that 308 runtime logging information will be dealt with using protocols 309 that do not require a formal data model, e.g., the Syslog protocol 310 defined in [RFC5424]. 312 o Capability and Status Information: Some of the status information 313 is modeled in the /lmap-state/agent subtree and teh /lmap-state/ 314 schedules subtree. Information about network interfaces can be 315 obtained from the interfaces YANG data model [RFC7223]. The list 316 of supported tasks is modeled in the /lmap-state/tasks subtree. 318 o Reporting Information: This is modeled by the report data model to 319 be implemented by the Collector. Measurement Agents send results 320 to the Collector via an RPC operation. 322 These six sections are build on the following common information 323 objects: 325 o Schedules: This is modeled in the /lmap/schedules subtree. 327 o Channels: Channels are not modeled since the NETCONF and RESTCONF 328 server configuration data model [I-D.ietf-netconf-server-model] 329 already provides a mechanism to configure NETCONF and RESTCONF 330 server channels. 332 o Task Configurations: This is modeled in the /lmap/tasks subtree. 334 o Event Information: This is modeled in the /lmap/events subtree. 336 4. YANG Modules 338 The modules import definitions from [RFC6991] and [RFC7223] and they 339 reference [RFC7398]. 341 file "ietf-lmap-common@2016-03-15.yang" 342 module ietf-lmap-common { 344 namespace "urn:ietf:params:xml:ns:yang:ietf-lmap-common"; 345 prefix "lmap"; 347 import ietf-inet-types { 348 prefix inet; 349 } 350 organization 351 "IETF Large-Scale Measurement Platforms Working Group"; 353 contact 354 "WG Web: 355 WG List: 357 Editor: Juergen Schoenwaelder 358 360 Editor: Vaibhav Bajpai 361 "; 363 description 364 "This module provides common definitions used by the data 365 models written for Large-Scale Measurement Platforms (LMAP). 366 This module defines typedefs and groupings but no schema 367 tree elements."; 369 revision "2016-03-15" { 370 description 371 "Initial version"; 372 reference 373 "RFC XXX: A YANG Data Model for LMAP Measurement Agents"; 374 } 376 /* 377 * Typedefs 378 */ 380 typedef identifier { 381 type string { 382 length "1..max"; 383 } 384 description 385 "An string value used to name something."; 386 } 388 typedef tag { 389 type string { 390 length "1..max"; 391 } 392 description 393 "A tag consists of at least one character."; 394 } 396 typedef glob-pattern { 397 type string { 398 length "1..max"; 399 } 400 description 401 "A glob style pattern (following POSIX.2 fnmatch() without 402 special treatment of file paths): 404 * matches a sequence of characters 405 ? matches a single character 406 [seq] matches any character in seq 407 [!seq] matches any character not in seq 409 A backslash followed by a character matches the following 410 character. In particular: 412 \* matches * 413 \? matches ? 414 \\ matches \ 416 A sequence seq may be a sequence of characters (e.g., [abc] 417 or a range of characters (e.g., [a-c])."; 418 } 420 typedef wildcard { 421 type string { 422 pattern '\*'; 423 } 424 description 425 "A wildcard for calendar scheduling entries."; 426 } 428 typedef month { 429 type enumeration { 430 enum january { 431 value 1; 432 description 433 "January of the Gregorian calendar."; 434 } 435 enum february { 436 value 2; 437 description 438 "February of the Gregorian calendar."; 439 } 440 enum march { 441 value 3; 442 description 443 "March of the Gregorian calendar."; 444 } 445 enum april { 446 value 4; 447 description 448 "April of the Gregorian calendar."; 449 } 450 enum may { 451 value 5; 452 description 453 "May of the Gregorian calendar."; 454 } 455 enum june { 456 value 6; 457 description 458 "June of the Gregorian calendar."; 459 } 460 enum july { 461 value 7; 462 description 463 "July of the Gregorian calendar."; 464 } 465 enum august { 466 value 8; 467 description 468 "August of the Gregorian calendar."; 469 } 470 enum september { 471 value 9; 472 description 473 "September of the Gregorian calendar."; 474 } 475 enum october { 476 value 10; 477 description 478 "October of the Gregorian calendar."; 479 } 480 enum november { 481 value 11; 482 description 483 "November of the Gregorian calendar."; 484 } 485 enum december { 486 value 12; 487 description 488 "December of the Gregorian calendar."; 489 } 490 } 491 description 492 "A type modeling the month in the Gregorian calendar."; 493 } 494 typedef month-or-all { 495 type union { 496 type month; 497 type wildcard; 498 } 499 description 500 "A month or a wildcard indicating all twelve months."; 501 } 503 typedef day-of-month { 504 type uint8 { range "1..31"; } 505 description 506 "A day of a month of the Gregorian calendar."; 507 } 509 typedef day-of-months-or-all { 510 type union { 511 type day-of-month; 512 type wildcard; 513 } 514 description 515 "A day of a months or a wildcard indicating all days 516 of a month."; 517 } 519 typedef weekday { 520 type enumeration { 521 enum monday { 522 value 1; 523 description 524 "Monday of the Gregorian calendar."; 525 } 526 enum tuesday { 527 value 2; 528 description 529 "Tuesday of the Gregorian calendar."; 530 } 531 enum wednesday { 532 value 3; 533 description 534 "Wednesday of the Gregorian calendar."; 535 } 536 enum thursday { 537 value 4; 538 description 539 "Thursday of the Gregorian calendar."; 540 } 541 enum friday { 542 value 5; 543 description 544 "Friday of the Gregorian calendar."; 545 } 546 enum saturday { 547 value 6; 548 description 549 "Saturday of the Gregorian calendar."; 550 } 551 enum sunday { 552 value 7; 553 description 554 "Sunday of the Gregorian calendar."; 555 } 556 } 557 description 558 "A type modeling the weekdays in the Gregorian calendar. 559 The numbering follows the ISO 8601 scheme."; 560 } 562 typedef weekday-or-all { 563 type union { 564 type weekday; 565 type wildcard; 566 } 567 description 568 "A weekday or a wildcard indicating all seven weekdays."; 569 } 571 typedef hour { 572 type uint8 { range "0..23"; } 573 description 574 "An hour of a day."; 575 } 577 typedef hour-or-all { 578 type union { 579 type hour; 580 type wildcard; 581 } 582 description 583 "An hour of a day or a wildcard indicating all hours 584 of a day."; 585 } 587 typedef minute { 588 type uint8 { range "0..59"; } 589 description 590 "A minute of an hour."; 591 } 593 typedef minute-or-all { 594 type union { 595 type minute; 596 type wildcard; 597 } 598 description 599 "A minute of an hour or a wildcard indicating all 600 minutes of an hour."; 601 } 603 typedef second { 604 type uint8 { range "0..59"; } 605 description 606 "A second of a minute."; 607 } 609 typedef second-or-all { 610 type union { 611 type second; 612 type wildcard; 613 } 614 description 615 "A second of a minute or a wildcard indicating all 616 seconds of a minute."; 617 } 619 typedef status-code { 620 type int32; 621 description 622 "A status code returned by the execution of a task. Note 623 that the actual range is implementation dependent but it 624 should be portable to use values in the range 0..127 for 625 regular exit codes. By convention, 0 indicates successful 626 termination. Negative values may be used to indicate 627 abnormal termination due to a signal; the absolute value 628 may identify the signal number in this case."; 629 } 631 typedef timezone-offset { 632 type string { 633 pattern 'Z|[\+\-]\d{2}:\d{2}'; 634 } 635 description 636 "A timezone-offset as it is used by the date-and-time type 637 defined in the ietf-yang-types module. The value Z is 638 equivalent to +00:00. The value -00:00 indicates and 639 unknown time-offset."; 640 reference 641 "RFC 6991: Common YANG Data Types"; 642 } 644 /* 645 * Groupings 646 */ 648 grouping metrics-grouping { 649 description 650 "This grouping models a list of entries in a metrics 651 registry."; 653 list metric { 654 key uri; 655 description 656 "A list of entries in a metrics registry."; 658 leaf uri { 659 type inet:uri; 660 description 661 "A URI identifying an entry in a metrics registry."; 662 } 664 leaf-list role { 665 type string; 666 description 667 "A set of roles for this metrics."; 668 } 669 } 670 } 672 grouping task-options-grouping { 673 description 674 "A list of options of a task. Each option is a name/value 675 pair (where the value may be absent)."; 677 list option { 678 key "id"; 679 ordered-by user; 680 description 681 "A list of options passed to the task. It is a list of 682 key / value pairs and may be used to model options. 683 Options may be used to identify the role of a task 684 or to pass a channel name to a task."; 686 leaf id { 687 type lmap:identifier; 688 description 689 "An identifier uniquely identifying an option. This 690 identifier is required by YANG to uniquely identify 691 a name value pair but it otherwise has no semantic 692 value"; 693 } 695 leaf name { 696 type string; 697 description 698 "The name of the option."; 699 } 701 leaf value { 702 type string; 703 description 704 "The value of the option."; 705 } 706 } 707 } 708 } 709 711 file "ietf-lmap-control@2016-03-15.yang" 712 module ietf-lmap-control { 714 namespace "urn:ietf:params:xml:ns:yang:ietf-lmap-control"; 715 prefix "lmapc"; 717 import ietf-yang-types { 718 prefix yang; 719 } 720 import ietf-inet-types { 721 prefix inet; 722 } 723 import ietf-lmap-common { 724 prefix lmap; 725 } 727 organization 728 "IETF Large-Scale Measurement Platforms Working Group"; 730 contact 731 "WG Web: 732 WG List: 734 Editor: Juergen Schoenwaelder 735 737 Editor: Vaibhav Bajpai 738 "; 740 description 741 "This module defines a data model for controlling measurement 742 agents that are part of a Large-Scale Measurement Platform 743 (LMAP). This data model is expected to be implemented by a 744 measurement agent."; 746 revision "2016-03-15" { 747 description 748 "Initial version"; 749 reference 750 "RFC XXX: A YANG Data Model for LMAP Measurement Agents"; 751 } 753 /* 754 * Typedefs 755 */ 757 typedef event-ref { 758 type leafref { 759 path "/lmap/events/event/name"; 760 } 761 description 762 "This type is used by data models that need to reference 763 a configured event source."; 764 } 766 typedef task-ref { 767 type leafref { 768 path "/lmap/tasks/task/name"; 769 } 770 description 771 "This type is used by data models that need to reference 772 a configured task."; 773 } 775 typedef schedule-ref { 776 type leafref { 777 path "/lmap/schedules/schedule/name"; 778 } 779 description 780 "This type is used by data models that need to reference 781 a configured schedule."; 782 } 784 /* 785 * Groupings 786 */ 788 grouping timing-start-end-grouping { 789 description 790 "A grouping that provides start and end times for 791 timing objects."; 792 leaf start { 793 type yang:date-and-time; 794 description 795 "The date and time when the timing object 796 starts to create triggers."; 797 } 798 leaf end { 799 type yang:date-and-time; 800 description 801 "The date and time when the timing object 802 stops to create triggers. 804 It is generally a good idea to always configure 805 an end time and to refresh the configuration 806 of timing object as needed to ensure that agents 807 that loose connectivity to their controller 808 do not continue their tasks forever."; 809 } 810 } 812 /* 813 * Configuration data nodes 814 */ 816 container lmap { 817 description 818 "Configuration of the LMAP agent."; 820 /* 821 * Agent Configuration 822 */ 824 container agent { 825 description 826 "Configuration of parameters affecting the whole 827 measurement agent."; 829 leaf agent-id { 830 type yang:uuid; 831 description 832 "The agent-id identifies a measurement agent with 833 a very low probability of collision. In certain 834 deployments, the agent-id may be considered 835 sensitive and hence this object is optional."; 836 } 838 leaf device-id { 839 type inet:uri; 840 description 841 "The device-id identifies a property of the 842 device running the measurement agent. In certain 843 deployments, the device-id may be considered 844 sensitive and hence this object is optional."; 845 } 847 leaf group-id { 848 type string; 849 description 850 "The group-id identifies a group of measurement 851 agents. In certain deployments, the group-id 852 may be considered less sensitive than the 853 agent-id."; 854 } 856 leaf measurement-point { 857 type string; 858 description 859 "The measurement point indicating where the 860 measurement agent is located on a path."; 861 reference 862 "RFC 7398: A Reference Path and Measurement Points 863 for Large-Scale Measurement of Broadband 864 Performance"; 865 } 867 leaf report-agent-id { 868 type boolean; 869 must '. != "true" or ../agent-id' { 870 description 871 "An agent-id must exist for this to be set 872 to true."; 873 } 874 default false; 875 description 876 "The 'report-agent-id' controls whether the 877 'agent-id' is reported to collectors if the 878 'group-id' is configured. If the 'group-id' 879 is not configured, the agent-id is always 880 reported."; 881 } 883 leaf report-measurement-point { 884 type boolean; 885 must '. != "true" or ../measurement-point' { 886 description 887 "A measurement-point must exist for this to be 888 set to true."; 889 } 890 default false; 891 description 892 "The 'report-measurement-point' controls whether 893 the 'measurement-point' is reported to collectors 894 if the 'measurement-point' is configured."; 895 } 897 leaf controller-timeout { 898 type uint32; 899 units "seconds"; 900 description 901 "A timer is started after each successful contact 902 with a controller. When the timer reaches the 903 controller-timeout, an event is raised indicating 904 that connectivity to the controller has been lost."; 905 } 906 } 908 /* 909 * Task Configuration 910 */ 912 container tasks { 913 description 914 "Configuration of LMAP tasks."; 916 list task { 917 key name; 918 description 919 "The list of tasks configured on the LMAP agent."; 921 leaf name { 922 type lmap:identifier; 923 description 924 "The unique name of a task."; 926 } 928 uses lmap:metrics-grouping; 930 leaf program { 931 type string; 932 description 933 "The (local) program to invoke in order to execute 934 the task."; 935 } 937 uses lmap:task-options-grouping { 938 description 939 "The list of task specific options."; 940 } 942 leaf suppress-by-default { 943 type boolean; 944 default true; 945 description 946 "Indicates whether the task will be suppressed by 947 a default supression."; 948 } 950 leaf-list tag { 951 type lmap:identifier; 952 description 953 "A tag contains additional information that is 954 passed with the result record to the collector. 955 A tag can be used, for example, to carry the 956 Measurement Cycle ID."; 957 } 958 } 959 } 961 /* 962 * Schedule Instructions 963 */ 965 container schedules { 966 description 967 "Configuration of LMAP schedules. Schedules control 968 which tasks are executed by the LMAP implementation."; 970 list schedule { 971 key name; 972 description 973 "Configuration of a particular schedule."; 975 leaf name { 976 type lmap:identifier; 977 description 978 "The locally-unique, administratively assigned name 979 for this schedule."; 980 } 982 leaf start { 983 type event-ref; 984 mandatory true; 985 description 986 "The event source controlling the start of the 987 scheduled actions."; 988 } 990 choice stop { 991 description 992 "This choice contains optional leafs that control the 993 graceful forced termination of scheduled actions. 994 When the end has been reached, the scheduled actions 995 should be forced to terminate the measurements. 996 This may involve being active some additional time in 997 order to properly finish the action's activity (e.g., 998 waiting for any still outstanding messages)."; 1000 leaf end { 1001 type event-ref; 1002 description 1003 "The event source controlling the graceful 1004 forced termination of the scheduled actions."; 1005 } 1007 leaf duration { 1008 type uint32; 1009 units "seconds"; 1010 description 1011 "The duration controlling the graceful forced 1012 termination of the scheduled actions."; 1013 } 1014 } 1016 leaf execution-mode { 1017 type enumeration { 1018 enum sequential { 1019 value 1; 1020 description 1021 "The actions of the schedule are executed 1022 sequentially."; 1024 } 1025 enum parallel { 1026 value 2; 1027 description 1028 "The actions of the schedule are executed 1029 concurrently"; 1030 } 1031 enum pipelined { 1032 value 3; 1033 description 1034 "The actions of the schedule are executed in a 1035 pipelined mode. Output created by an action is 1036 passed as input to the subsequent action."; 1037 } 1038 } 1039 default pipelined; 1040 description 1041 "The execution mode of this schedule determins in 1042 which order the actions of the schedule are executed."; 1043 } 1045 leaf-list tag { 1046 type lmap:tag; 1047 description 1048 "A list of schedule specific tags that are 1049 reported together with the measurement results 1050 to a collector."; 1051 } 1053 leaf-list suppression-tag { 1054 type lmap:tag; 1055 description 1056 "A list of suppression tags that are used to select 1057 schedules to be suppressed."; 1058 } 1060 list action { 1061 key name; 1062 description 1063 "An action describes a task that is invoked by the 1064 schedule. Multiple actions are invoked sequentially."; 1066 leaf name { 1067 type lmap:identifier; 1068 description 1069 "The unique identifier for this action."; 1070 } 1071 leaf task { 1072 type task-ref; 1073 mandatory true; 1074 description 1075 "The task invoked by this action."; 1076 } 1078 container parameters { 1079 description 1080 "This container is a place-holder for run-time 1081 parameters defined in task-specific or 1082 metric-specific data models augmenting the 1083 base lmap control data model."; 1085 choice extension { 1086 description 1087 "This choice is provided to augment in different 1088 sets of parameters."; 1089 } 1090 } 1092 uses lmap:task-options-grouping { 1093 description 1094 "The list of action specific options that are 1095 appended to the list of task specific options."; 1096 } 1098 leaf-list destination { 1099 type schedule-ref; 1100 description 1101 "A schedule of receiving the output produced by 1102 this action. A queue is internally used to pass 1103 results to another schedule. The behaviour of 1104 an action passing data to its own schedule is 1105 implementation specific. 1107 Data passed to a sequential or pipelined schedule 1108 is consumed by the schedule's first action. Data 1109 passed to a parallel schedule is consumed by all 1110 actions of the schedule."; 1111 } 1113 leaf-list tag { 1114 type lmap:tag; 1115 description 1116 "A list of action specific tags that are 1117 reported together with the measurement results 1118 to a collector."; 1120 } 1122 leaf-list suppression-tag { 1123 type lmap:tag; 1124 description 1125 "A list of suppression tags that are used to select 1126 actions to be suppressed."; 1127 } 1128 } 1129 } 1130 } 1132 /* 1133 * Suppression Instructions 1134 */ 1136 container suppressions { 1137 description 1138 "Suppression information to prevent schedules or 1139 certain actions from starting."; 1141 list suppression { 1142 key name; 1143 description 1144 "Configuration of a particular suppression."; 1146 leaf name { 1147 type lmap:identifier; 1148 description 1149 "The locally-unique, administratively assigned name 1150 for this suppression."; 1151 } 1153 leaf start { 1154 type event-ref; 1155 description 1156 "The event source controlling the start of the 1157 suppression period."; 1158 } 1160 leaf end { 1161 type event-ref; 1162 description 1163 "The event source controlling the end of the 1164 suppression period. If not present, supression 1165 continues indefinitely."; 1166 } 1167 leaf-list match { 1168 type lmap:glob-pattern; 1169 description 1170 "A list of suppression tags. The suppression will 1171 apply to all schedules (and their actions) that 1172 have a matching value in their suppression-tags 1173 and to all actions that have a matching value in 1174 their suppression-tags."; 1175 } 1177 leaf stop-running { 1178 type boolean; 1179 default false; 1180 description 1181 "Setting 'stop-running' to true will cause running 1182 tasks to be terminated if suppression is activated. 1183 Otherwise, running tasks will not be affected if 1184 suppression is activated."; 1185 } 1186 } 1187 } 1189 /* 1190 * Event Instructions 1191 */ 1193 container events { 1194 description 1195 "Configuration of LMAP events. 1197 Implementations may be forced to delay acting 1198 upon the occurance of events in the face of local 1199 constraints. An action triggered by an event 1200 therefore should not rely on the accuracy 1201 provided by the scheduler implementation."; 1203 list event { 1204 key name; 1205 description 1206 "The list of event sources configured on the 1207 LMAP agent."; 1209 leaf name { 1210 type lmap:identifier; 1211 description 1212 "The unique name of an event source."; 1213 } 1214 choice event-type { 1215 description 1216 "Different types of events are handled by 1217 different branches of this choice. Note that 1218 this choice can be extended via augmentations."; 1220 case periodic { 1221 container periodic { 1222 description 1223 "A periodic timing object triggers periodically 1224 according to a regular interval."; 1226 leaf interval { 1227 type uint32 { 1228 range "1..max"; 1229 } 1230 units "seconds"; 1231 mandatory true; 1232 description 1233 "The number of seconds between two triggers 1234 generated by this periodic timing object."; 1235 } 1236 uses timing-start-end-grouping; 1237 } 1238 } 1240 case calendar { 1241 container calendar { 1242 description 1243 "A calendar timing object triggers based on the 1244 current calendar date and time."; 1246 leaf-list month { 1247 type lmap:month-or-all; 1248 min-elements 1; 1249 description 1250 "A month at which this calendar timing will 1251 trigger. The wildcard means all months."; 1252 } 1254 leaf-list day-of-month { 1255 type lmap:day-of-months-or-all; 1256 min-elements 1; 1257 description 1258 "A day of the month at which this calendar 1259 timing will trigger. The wildcard means all 1260 days of a month."; 1261 } 1262 leaf-list day-of-week { 1263 type lmap:weekday-or-all; 1264 min-elements 1; 1265 description 1266 "A weekday at which this calendar timing will 1267 trigger. The wildcard means all weekdays."; 1268 } 1270 leaf-list hour { 1271 type lmap:hour-or-all; 1272 min-elements 1; 1273 description 1274 "An hour at which this calendar timing will 1275 trigger. The wildcard means all hours of a 1276 day."; 1277 } 1279 leaf-list minute { 1280 type lmap:minute-or-all; 1281 min-elements 1; 1282 description 1283 "A minute at which this calendar timing will 1284 trigger. The wildcard means all minutes of 1285 an hour."; 1286 } 1288 leaf-list second { 1289 type lmap:second-or-all; 1290 min-elements 1; 1291 description 1292 "A second at which this calendar timing will 1293 trigger. The wildcard means all seconds of 1294 a minute."; 1295 } 1297 leaf timezone-offset { 1298 type lmap:timezone-offset; 1299 description 1300 "The timezone in which this calendar timing 1301 object will be evaluated. If not present, 1302 the systems' local timezone will be used."; 1303 } 1304 uses timing-start-end-grouping; 1305 } 1306 } 1308 case one-off { 1309 container one-off { 1310 description 1311 "A one-off timing object triggers exactly once."; 1313 leaf time { 1314 type yang:date-and-time; 1315 mandatory true; 1316 description 1317 "This one-off timing object triggers once at 1318 the configured date and time."; 1319 } 1320 } 1321 } 1323 case immediate { 1324 leaf immediate { 1325 type empty; 1326 mandatory true; 1327 description 1328 "This immediate event object triggers immediately 1329 when it is configured."; 1330 } 1331 } 1333 case startup { 1334 leaf startup { 1335 type empty; 1336 mandatory true; 1337 description 1338 "This startup event object triggers whenever the 1339 LMAP agent (re)starts."; 1340 } 1341 } 1343 case controller-lost { 1344 leaf controller-lost { 1345 type empty; 1346 mandatory true; 1347 description 1348 "The controller-lost event object triggers when 1349 the connectivity to the controller has been lost 1350 for at least 'controller-timeout' seconds."; 1351 } 1352 } 1354 case controller-connected { 1355 leaf controller-connected { 1356 type empty; 1357 mandatory true; 1358 description 1359 "The controller-connected event object triggers 1360 when the connectivity to the controller has been 1361 restored after it was lost for at least 1362 'controller-timeout' seconds."; 1363 } 1364 } 1365 } 1367 leaf random-spread { 1368 type uint32; 1369 units seconds; 1370 description 1371 "This optional leaf adds a random spread to the 1372 computation of the event's trigger time. The 1373 random spread is a uniformly distributed random 1374 number taken from the interval [0:random-spread]."; 1375 } 1376 } 1377 } 1378 } 1380 /* 1381 * The state subtree provides information about the capabilities 1382 * and the current status of the MA. 1383 */ 1385 container lmap-state { 1386 config false; 1387 description 1388 "A tree exporting state information about the LMAP agent."; 1390 container agent { 1391 description 1392 "Operations state of the measurement agent."; 1394 leaf agent-id { 1395 type yang:uuid; 1396 mandatory true; 1397 description 1398 "The agent-id identifies a measurement agent with 1399 a very low probability of collision. In certain 1400 deployments, the agent-id may be considered 1401 sensitive and hence this object is optional."; 1402 } 1404 leaf device-id { 1405 type inet:uri; 1406 mandatory true; 1407 description 1408 "The device-id identifies a property of the 1409 device running the measurement agent. In certain 1410 deployments, the device-id may be considered 1411 sensitive and hence this object is optional."; 1412 } 1413 leaf hardware { 1414 type string; 1415 mandatory true; 1416 description 1417 "A short description of the hardware the measurement 1418 agent is running on. This should include the version 1419 number of the hardware"; 1420 } 1421 leaf firmware { 1422 type string; 1423 mandatory true; 1424 description 1425 "A short description of the firmware the measurement 1426 agent is running on. This should include the version 1427 number of the firmware."; 1428 } 1429 leaf version { 1430 type string; 1431 mandatory true; 1432 description 1433 "A short description of the software implementing the 1434 measurement agent. This should include the version 1435 number of the measurement agent software."; 1436 } 1437 leaf last-started { 1438 type yang:date-and-time; 1439 mandatory true; 1440 description 1441 "The date and time the measurement agent last started."; 1442 } 1443 } 1445 container tasks { 1446 description 1447 "Available LMAP tasks, including information about their 1448 last execution and their last failed execution."; 1450 list task { 1451 key name; 1452 description 1453 "The list of tasks available on the LMAP agent."; 1455 leaf name { 1456 type lmap:identifier; 1457 description 1458 "The unique name of a task."; 1459 } 1461 uses lmap:metrics-grouping; 1463 leaf version { 1464 type string; 1465 description 1466 "A short description of the software implementing 1467 the task. This should include the version 1468 number of the measurement task software."; 1469 } 1471 leaf program { 1472 type string; 1473 description 1474 "The (local) program to invoke in order to execute 1475 the task."; 1476 } 1477 } 1478 } 1480 container schedules { 1481 description 1482 "State of LMAP schedules."; 1484 list schedule { 1485 key name; 1486 description 1487 "State of a particular schedule."; 1489 leaf name { 1490 type lmap:identifier; 1491 description 1492 "The locally-unique, administratively assigned name 1493 for this schedule."; 1494 } 1496 leaf state { 1497 type enumeration { 1498 enum enabled { 1499 value 1; 1500 description 1501 "The value 'enabled' indicates that the 1502 schedule is currently enabled."; 1504 } 1505 enum disabled { 1506 value 2; 1507 description 1508 "The value 'disabled' indicates that the 1509 schedule is currently disabled."; 1510 } 1511 enum running { 1512 value 3; 1513 description 1514 "The value 'running' indicates that the 1515 schedule is currently running."; 1516 } 1517 enum suppressed { 1518 value 4; 1519 description 1520 "The value 'suppressed' indicates that the 1521 schedule is currently suppressed."; 1522 } 1523 } 1524 description 1525 "The current state of the schedule."; 1526 } 1528 leaf invocations { 1529 type yang:counter32; 1530 description 1531 "Number of invocations of this schedule. This counter 1532 does not include suppressed invocations or invocations 1533 that were prevented due to an overlap with a previous 1534 invocation of this schedule."; 1535 } 1537 leaf suppressions { 1538 type yang:counter32; 1539 description 1540 "Number of suppressed executions of this schedule."; 1541 } 1543 leaf overlaps { 1544 type yang:counter32; 1545 description 1546 "Number of executions prevented due to overlaps with 1547 a previous invocation of this schedule."; 1548 } 1550 leaf failures { 1551 type yang:counter32; 1552 description 1553 "Number of failed executions of this schedule. A 1554 failed execution is an execution where at least 1555 one action failed."; 1556 } 1558 leaf last-invocation { 1559 type yang:date-and-time; 1560 description 1561 "The date and time of the last invocation of 1562 this schedule."; 1563 } 1565 list action { 1566 key name; 1567 description 1568 "The state of the actions associated with this 1569 schedule entry."; 1571 leaf name { 1572 type lmap:identifier; 1573 description 1574 "The unique identifier for this action."; 1575 } 1577 leaf state { 1578 type enumeration { 1579 enum enabled { 1580 value 1; 1581 description 1582 "The value 'enabled' indicates that the 1583 action is currently enabled."; 1584 } 1585 enum disabled { 1586 value 2; 1587 description 1588 "The value 'disabled' indicates that the 1589 action is currently disabled."; 1590 } 1591 enum running { 1592 value 3; 1593 description 1594 "The value 'running' indicates that the 1595 action is currently runnning."; 1596 } 1597 enum suppressed { 1598 value 4; 1599 description 1600 "The value 'suppressed' indicates that the 1601 action is currently suppressed."; 1602 } 1603 } 1604 description 1605 "The current state of the action."; 1606 } 1608 leaf invocations { 1609 type yang:counter32; 1610 description 1611 "Number of invocations of this action. This counter 1612 does not include suppressed invocations or invocations 1613 that were prevented due to an overlap with a previous 1614 invocation of this action."; 1615 } 1617 leaf suppressions { 1618 type yang:counter32; 1619 description 1620 "Number of suppressed executions of this action."; 1621 } 1623 leaf overlaps { 1624 type yang:counter32; 1625 description 1626 "Number of executions prevented due to overlaps with 1627 a previous invocation of this action."; 1628 } 1630 leaf failures { 1631 type yang:counter32; 1632 description 1633 "Number of failed executions of this action."; 1634 } 1636 leaf last-invocation { 1637 type yang:date-and-time; 1638 description 1639 "The date and time of the last invocation of 1640 this action."; 1641 } 1643 leaf last-completion { 1644 type yang:date-and-time; 1645 description 1646 "The date and time of the last completion of 1647 this action."; 1649 } 1651 leaf last-status { 1652 type lmap:status-code; 1653 description 1654 "The status code returned by the last execution of 1655 this action."; 1656 } 1658 leaf last-message { 1659 type string; 1660 description 1661 "The status message produced by the last execution 1662 of this action."; 1663 } 1665 leaf last-failed-completion { 1666 type yang:date-and-time; 1667 description 1668 "The date and time of the last failed completion 1669 of this action."; 1670 } 1672 leaf last-failed-status { 1673 type lmap:status-code; 1674 description 1675 "The status code returned by the last failed 1676 execution of this action."; 1677 } 1679 leaf last-failed-message { 1680 type string; 1681 description 1682 "The status message produced by the last failed 1683 execution of this action."; 1684 } 1685 } 1686 } 1687 } 1689 container suppressions { 1690 description 1691 "State of LMAP suppressions."; 1693 list suppression { 1694 key name; 1695 description 1696 "State of a particular suppression."; 1698 leaf name { 1699 type lmap:identifier; 1700 description 1701 "The locally-unique, administratively assigned name 1702 for this suppression."; 1703 } 1705 leaf state { 1706 type enumeration { 1707 enum enabled { 1708 value 1; 1709 description 1710 "The value 'enabled' indicates that the 1711 suppression is currently enabled."; 1712 } 1713 enum disabled { 1714 value 2; 1715 description 1716 "The value 'disabled' indicates that the 1717 suppression is currently disabled."; 1718 } 1719 enum active { 1720 value 3; 1721 description 1722 "The value 'active' indicates that the 1723 suppression is currently active."; 1724 } 1725 } 1726 description 1727 "The current state of the suppression."; 1728 } 1729 } 1730 } 1731 } 1732 } 1733 1735 file "ietf-lmap-report@2016-03-21.yang" 1736 module ietf-lmap-report { 1738 namespace "urn:ietf:params:xml:ns:yang:ietf-lmap-report"; 1739 prefix "lmapr"; 1741 import ietf-yang-types { 1742 prefix yang; 1743 } 1744 import ietf-lmap-common { 1745 prefix lmap; 1746 } 1748 organization 1749 "IETF Large-Scale Measurement Platforms Working Group"; 1751 contact 1752 "WG Web: 1753 WG List: 1755 Editor: Juergen Schoenwaelder 1756 1758 Editor: Vaibhav Bajpai 1759 "; 1761 description 1762 "This module defines a data model for reporting results from 1763 measurement agents, which are part of a Large-Scale Measurement 1764 Platform (LMAP), to result data collectors. This data model is 1765 expected to be implemented by a collector."; 1767 revision "2016-03-21" { 1768 description 1769 "Initial version"; 1770 reference 1771 "RFC XXX: A YANG Data Model for LMAP Measurement Agents"; 1772 } 1774 rpc report { 1775 description 1776 "The report operation is used by an LMAP measurement agent to 1777 submit measurement results produced by measurement tasks to 1778 a collector."; 1780 input { 1782 leaf date { 1783 type yang:date-and-time; 1784 mandatory true; 1785 description 1786 "The date and time when this result report was sent to 1787 a collector."; 1788 } 1790 leaf agent-id { 1791 type yang:uuid; 1792 description 1793 "The agent-id of the agent from which this 1794 report originates."; 1795 } 1797 leaf group-id { 1798 type string; 1799 description 1800 "The group-id of the agent from which this 1801 report originates."; 1802 } 1804 leaf measurement-point { 1805 type string; 1806 description 1807 "The measurement-point of the agent from which this 1808 report originates."; 1809 } 1811 list result { 1812 description 1813 "The list of tasks for which results are reported."; 1815 leaf schedule-name { 1816 type lmap:identifier; 1817 description 1818 "The name of the schedules that produced the result."; 1819 } 1821 leaf action-name { 1822 type lmap:identifier; 1823 description 1824 "The name of the action in the schedule that produced 1825 the result."; 1826 } 1828 leaf task-name { 1829 type lmap:identifier; 1830 description 1831 "The name of the task that produced the result."; 1832 } 1834 uses lmap:metrics-grouping; 1836 uses lmap:task-options-grouping { 1837 description 1838 "The list of options there were in use then the 1839 measurement was performed. This list must include 1841 both the task specific options as well as the action 1842 specific options."; 1843 } 1845 leaf-list tag { 1846 type lmap:tag; 1847 description 1848 "A tag contains additional information that is passed 1849 with the result record to the collector. This is the 1850 joined set of tags defined for the task object and the 1851 action object. A tag can be used to carry the 1852 Measurement Cycle ID."; 1853 } 1855 leaf start { 1856 type yang:date-and-time; 1857 mandatory true; 1858 description 1859 "The date and time when the measurement producing 1860 this result started."; 1861 } 1863 leaf end { 1864 type yang:date-and-time; 1865 description 1866 "The date and time when the measurement producing 1867 this result stopped."; 1868 } 1870 leaf-list conflict { 1871 type lmap:identifier; 1872 description 1873 "The names of tasks overlapping with the execution 1874 of the task that has produced this result."; 1875 } 1877 list table { 1878 description 1879 "A list of result tables."; 1881 leaf-list column { 1882 type string; 1883 description 1884 "An ordered list of column labels. The order is 1885 determined by the system and must match the order 1886 of the columns in the result rows."; 1887 } 1888 list row { 1889 description 1890 "The rows of a result table."; 1892 leaf-list value { 1893 type string; 1894 description 1895 "The value of a cell in the result row."; 1896 } 1897 } 1898 } 1899 } 1900 } 1901 } 1902 } 1903 1905 5. Security Considerations 1907 The YANG module defined in this memo is designed to be accessed via 1908 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 1909 secure transport layer and the mandatory to implement secure 1910 transport is SSH [RFC6242]. The NETCONF access control model 1911 [RFC6536] provides the means to restrict access for particular 1912 NETCONF users to a pre-configured subset of all available NETCONF 1913 protocol operations and content. 1915 There are a number of data nodes defined in this YANG module which 1916 are writable/creatable/deletable (i.e., config true, which is the 1917 default). These data nodes may be considered sensitive or vulnerable 1918 in some network environments. Write operations (e.g., edit-config) 1919 to these data nodes without proper protection can have a negative 1920 effect on network operations. These are the subtrees and data nodes 1921 and their sensitivity/vulnerability: 1923 /lmap/agent This subtree configures general properties of 1924 the measurement agent such as its identity, its 1925 measurement point or controller timeout. This 1926 subtree should only have write access for the 1927 system responsible to configure the measurement 1928 agent. 1930 /lmap/tasks This subtree configures the tasks that can be 1931 invoked by a controller. This subtree should 1932 only have write access for the system 1933 responsible to configure the measurement agent. 1934 Care must be taken to not expose tasks to a 1935 controller that can cause damage to the system 1936 or the network. 1938 /lmap/schedules This subtree is used by a controller to define 1939 the schedules and actions that are executed 1940 when certain events occur. Unauthorized access 1941 can cause unwanted load on the device or 1942 network or it might direct measurement traffic 1943 to targets that become victims of an attack. 1945 /lmap/suppressions This subtree is used by a controller to define 1946 suppressions that can temporarily disable the 1947 execution of schedules or actions. 1948 Unauthorized access can either disable 1949 measurements that should normally take place or 1950 it can cause measurements to take place during 1951 times when normally no measurements should take 1952 place. 1954 /lmap/events This subtree is used by a controller to define 1955 events that trigger the execution of schedules 1956 and actions. Unauthorized access can either 1957 disable measurements that should normally take 1958 place or it can cause measurements to take 1959 place during times when normally no 1960 measurements should take place or at frequency 1961 that is higher than normally expected. 1963 Some of the readable data nodes in this YANG module may be considered 1964 sensitive or vulnerable in some network environments. It is thus 1965 important to control read access (e.g., via get, get-config or 1966 notification) to these data nodes. These are the subtrees and data 1967 nodes and their sensitivity/vulnerability: 1969 /lmap-state/agent This subtree provides information about the 1970 implementation (including version numbers). 1971 This information may be used to mount 1972 targeted attacks against the 1973 implementation. 1975 /lmap-state/tasks This subtree provides information about the 1976 tasks (including version numbers). This 1977 information may be used to mount targeted 1978 attacks against the implementation. 1980 /lmap-state/schedules This subtree provides information about the 1981 schedules executed on the system. This 1982 information may be used to check whether 1983 attacks against the implementation are 1984 effective. 1986 /lmap-state/suppressions This subtree provides information about the 1987 suppressions executed on the system. This 1988 information may be used to predict time 1989 periods where measurements take place (or 1990 do not take place). 1992 Some of the RPC operations in this YANG module may be considered 1993 sensitive or vulnerable in some network environments. It is thus 1994 important to control access to these operations. These are the 1995 operations and their sensitivity/vulnerability: 1997 /report The report operation is used to send locally collected 1998 measurement results to a remote collector. Unauthorized 1999 access may leak measurement results. 2001 The data model uses a number of identifiers that are set by the 2002 controller. Implementors may find these identifiers useful for the 2003 identification of resources, e.g., to identify objects in a 2004 filesystem providing temporary storage. Since the identifiers used 2005 by the YANG data model may allow characters that may be given special 2006 interpretation in a specific context, implementations MUST ensure 2007 that identifiers are properly mapped into safe identifiers. 2009 The data model allows to specify options in the form of name value 2010 pairs that are passed to programs. Implementers MUST taken care that 2011 option names and values are passed literally to programs. In 2012 particular, it MUST be avoided that any shell expansions are 2013 performed that may alter the option names and values. 2015 6. IANA Considerations 2017 This document registers a URI in the "IETF XML Registry" [RFC3688]. 2018 Following the format in RFC 3688, the following registrations have 2019 been made. 2021 URI: urn:ietf:params:xml:ns:yang:ietf-lmap-common 2022 Registrant Contact: The IESG. 2023 XML: N/A; the requested URI is an XML namespace. 2025 URI: urn:ietf:params:xml:ns:yang:ietf-lmap-control 2026 Registrant Contact: The IESG. 2027 XML: N/A; the requested URI is an XML namespace. 2029 URI: urn:ietf:params:xml:ns:yang:ietf-lmap-report 2030 Registrant Contact: The IESG. 2031 XML: N/A; the requested URI is an XML namespace. 2033 This document registers a YANG module in the "YANG Module Names" 2034 registry [RFC6020]. 2036 name: ietf-lmap-common 2037 namespace: urn:ietf:params:xml:ns:yang:ietf-lmap-common 2038 prefix: lmap 2039 reference: RFC XXXX 2041 name: ietf-lmap-control 2042 namespace: urn:ietf:params:xml:ns:yang:ietf-lmap-control 2043 prefix: lmapc 2044 reference: RFC XXXX 2046 name: ietf-lmap-report 2047 namespace: urn:ietf:params:xml:ns:yang:ietf-lmap-report 2048 prefix: lmapr 2049 reference: RFC XXXX 2051 7. Acknowledgements 2053 Juergen Schoenwaelder and Vaibhav Bajpai worked in part on the Leone 2054 research project, which received funding from the European Union 2055 Seventh Framework Programme [FP7/2007-2013] under grant agreement 2056 number 317647. 2058 Juergen Schoenwaelder and Vaibhav Bajpai were partly funded by 2059 Flamingo, a Network of Excellence project (ICT-318488) supported by 2060 the European Commission under its Seventh Framework Programme. 2062 8. References 2064 8.1. Normative References 2066 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2067 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 2068 RFC2119, March 1997, 2069 . 2071 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2072 the Network Configuration Protocol (NETCONF)", RFC 6020, 2073 DOI 10.17487/RFC6020, October 2010, 2074 . 2076 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", RFC 2077 6991, DOI 10.17487/RFC6991, July 2013, 2078 . 2080 8.2. Informative References 2082 [I-D.ietf-lmap-information-model] 2083 Burbridge, T., Eardley, P., Bagnulo, M., and J. 2084 Schoenwaelder, "Information Model for Large-Scale 2085 Measurement Platforms (LMAP)", draft-ietf-lmap- 2086 information-model-08 (work in progress), March 2016. 2088 [I-D.ietf-netconf-server-model] 2089 Watsen, K. and J. Schoenwaelder, "NETCONF Server and 2090 RESTCONF Server Configuration Models", draft-ietf-netconf- 2091 server-model-09 (work in progress), March 2016. 2093 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2094 DOI 10.17487/RFC3688, January 2004, 2095 . 2097 [RFC5424] Gerhards, R., "The Syslog Protocol", RFC 5424, DOI 10 2098 .17487/RFC5424, March 2009, 2099 . 2101 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2102 and A. Bierman, Ed., "Network Configuration Protocol 2103 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2104 . 2106 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 2107 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 2108 . 2110 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 2111 Protocol (NETCONF) Access Control Model", RFC 6536, DOI 10 2112 .17487/RFC6536, March 2012, 2113 . 2115 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 2116 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 2117 . 2119 [RFC7398] Bagnulo, M., Burbridge, T., Crawford, S., Eardley, P., and 2120 A. Morton, "A Reference Path and Measurement Points for 2121 Large-Scale Measurement of Broadband Performance", RFC 2122 7398, DOI 10.17487/RFC7398, February 2015, 2123 . 2125 [RFC7594] Eardley, P., Morton, A., Bagnulo, M., Burbridge, T., 2126 Aitken, P., and A. Akhter, "A Framework for Large-Scale 2127 Measurement of Broadband Performance (LMAP)", RFC 7594, 2128 DOI 10.17487/RFC7594, September 2015, 2129 . 2131 Appendix A. Open Issues 2133 A.1. Purpose of /lmap-state/tasks 2135 Proposal: Tasks are configured in /lmap/tasks and even marked as nacm 2136 :default-deny-write (see RFC 6536) since configuring programs that 2137 can be invoked by a controller is an operation that may impact the 2138 security of the device. See also the related open issue on the 2139 information model. If we do this, then /lmap-state/tasks should 2140 probably only report the version number. 2142 A.2. Streamline the reporting model 2144 The reporting model is somewhat verbose; perhaps things can be 2145 streamlined and be made more efficient. Implementation experience 2146 will help to work this out. 2148 A.3. Examples 2150 Do we want to keep the examples? If yes, they should be better 2151 aligned. If we keep the examples, do we need to keep both versions 2152 (XML and JSON)? 2154 Appendix B. Non-editorial Changes since -03 2156 o Reworked the reporting data model to align it with the changes in 2157 the information model. 2159 Appendix C. Non-editorial Changes since -02 2161 o Added a mechanism to enforce a runtime limit for schedules. 2163 o Added security considerations text warning about possible shell 2164 expansions of options. 2166 o Restricted all user-defined names and tags to lmap:identifier. 2167 Added security considerations text to make implementors aware of 2168 possible security issues if identifiers are naively mapped to say 2169 filesystem paths. 2171 o Schedules and actions now have tags (echoed to the collector) and 2172 suppression tags (used for suppression selection). 2174 o Introduced glob-style pattern to match tags. 2176 o Added an example module for IPPM udp latency metrics to 2177 demonstrate the usage of the extension mechanism. 2179 o Introduced parameters, an extension point for task/metric specific 2180 parameters defined in augmenting YANG modules. 2182 o Introduced the typedefs event-ref, task-ref, and schedule-ref. 2184 o Changed schedule/event to schedule/start and added the optional 2185 schedule/stop and schedule/duration leafs. 2187 Appendix D. Non-editorial Changes since -01 2189 o Updated and split examples (config vs state vs report). 2191 o Refactored the definitions so that common definitions used by both 2192 the control and report data models are in the new module ietf- 2193 lmap-common. 2195 o A report is submitted via an RPC operation instead of using a 2196 notification. 2198 o The default execution mode is pipelined. 2200 o Clarified which action consumes data in sequential, pipelines, and 2201 parallel execution mode. 2203 o Added /lmap/agent/measurement-point, /lmap/agent/report- 2204 measurement-point, and /report/measurement-point to configure and 2205 report the measurement point. 2207 o Turned /lmap/suppression into a list /lmap/suppressions/ 2208 suppression that uses a start and stop event to define the 2209 beginning and end of a suppression period. 2211 o Added controller-lost an controller-ok event choices to /lmap/ 2212 events/event. 2214 o Added a metrics-grouping to identify entries in a metric registry 2215 and associated roles. 2217 o Added /lmap-state/schedules to report the status of schedules and 2218 their actions. Refactored /lmap-state/tasks to only report the 2219 task capabilities. 2221 Appendix E. Non-editorial Changes since -00 2223 o A task can now reference multiply registry entries. 2225 o Schedules are triggered by Events instead of Timings; Timings are 2226 just one of many possible event sources. 2228 o Actions feed into other Schedules (instead of Actions within other 2229 Schedules). 2231 o Removed the notion of multiple task outputs. 2233 o Support for sequential, parallel, and pipelined execution of 2234 Actions. 2236 Appendix F. Example IPPM Module for UDP Latency Metrics 2238 module example-ietf-ippm-udp-latency { 2240 namespace "urn:example:ietf-ippm-udp-latency"; 2241 prefix "ippm-udp-latency"; 2243 import ietf-inet-types { 2244 prefix inet; 2245 } 2247 import ietf-lmap-control { 2248 prefix "lmap"; 2249 } 2250 augment "/lmap:lmap/lmap:schedules/lmap:schedule/lmap:action" 2251 + "/lmap:parameters/lmap:extension" { 2252 description 2253 "This augmentation adds parameters specific to IPPM UDP 2254 latency metrics."; 2256 case "ietf-ippm-udp-latency" { 2257 leaf src-ip { 2258 type inet:ip-address; 2259 description 2260 "The source IP address of the UDP measurement traffic."; 2261 } 2263 leaf src-port { 2264 type inet:port-number; 2265 description 2266 "The source port number of the UDP measurement traffic."; 2267 } 2269 leaf dst-ip { 2270 type inet:ip-address; 2271 description 2272 "The destination IP address of the UDP measurement traffic."; 2273 } 2275 leaf dst-port { 2276 type inet:port-number; 2277 description 2278 "The destination port number of the UDP measurement traffic."; 2279 } 2281 leaf poisson-lambda { 2282 type decimal64 { 2283 fraction-digits 4; 2284 } 2285 units "seconds"; 2286 default 1.0000; 2287 description 2288 "The average interval for the poisson stream with a resolution 2289 of 0.0001 seconds (0.1 ms)."; 2290 } 2292 leaf poisson-limit { 2293 type decimal64 { 2294 fraction-digits 4; 2295 } 2296 units "seconds"; 2297 default 30.0000; 2298 description 2299 "The upper limit on the poisson distribution with a resolution 2300 of 0.0001 seconds (0.1 ms)."; 2301 } 2302 } 2303 } 2304 } 2306 Appendix G. Example Configuration (XML) 2308 2309 2311 2312 550e8400-e29b-41d4-a716-446655440000 2313 urn:dev:mac:0024befffe804ff1 2314 network measurement at the north-pole 2315 true 2316 2318 2319 2320 2321 iperf-server 2322 /usr/bin/iperf 2323 2327 passive 2328 iperf 2329 2331 2332 2333 iperf-client 2334 /usr/bin/iperf 2335 2339 active 2340 iperf 2341 2343 2344 2345 lmap-reporting-task 2346 /usr/bin/lmap-reporter 2347 2351 2353 2354 fcc-measurement-suite 2355 /usr/bin/fcc-suite 2356 2358 2359 ippm-udp-latency-client 2360 /usr/bin/ippm-udp-latency 2361 2362 urn:example:what? 2363 client 2364 2365 active 2366 2367 2369 2370 2371 2372 fcc-campain-2016 2373 fcc-hourly-sep-2016 2374 600 2375 pipelined 2376 2377 fcc-measurement 2378 fcc-measurement-suite 2379 2380 2381 fcc-report 2382 lmap-reporting-task 2383 2387 2388 2390 2393 2394 iperf-hourly 2395 hourly 2396 sequential 2397 2398 iperf-hourly-mlab1 2399 iperf-client 2400 2404 2405 2406 iperf-hourly-mlab2 2407 iperf-client 2408 2412 report-collector 2413 report-shadow-collector 2414 2415 2417 2418 2419 startup 2420 startup 2421 2422 iperf-server 2423 iperf-server 2424 2425 2427 2428 2429 report-collector 2430 once-every-six-hours 2431 2432 report-action 2433 lmap-reporting-task 2434 2438 2439 2440 2441 2442 report-shadow-collector 2443 daily 2444 2445 report-action 2446 lmap-reporting-task 2447 2451 2452 2454 2455 2456 ippm-udp-latency 2457 hourly 2458 sequential 2459 2460 ippm-udp-latency 2461 ippm-udp-latency-client 2462 2463 192.0.2.1 2464 54321 2465 192.0.2.2 2466 12345 2467 42 2468 2469 2470 2471 ippm-udp-latency-report 2472 lmap-reporting-task 2473 2477 2478 2479 2481 2482 2483 2484 orphaned 2485 controller-lost 2486 controller-connected 2487 * 2489 2491 2492 2493 new-year-evening 2494 dec-31-11:00 2495 jan-01-15:00 2496 active 2497 2498 2500 2501 2502 fcc-hourly-sep-2016 2503 2504 3600000 2505 2016-09-01T00:00:00+00:00 2506 2016-10-01T00:00:00+00:00 2507 2508 300000 2509 2511 2512 monthly 2513 2514 * 2515 * 2516 1 2517 0 2518 0 2519 0 2520 +00:00 2521 2522 2524 2525 weekly 2526 2527 * 2528 monday 2529 * 2530 0 2531 0 2532 0 2533 +00:00 2534 2535 2536 2537 daily 2538 2539 * 2540 * 2541 * 2542 0 2543 0 2544 0 2545 +00:00 2546 2547 2549 2550 hourly 2551 2552 * 2553 * 2554 * 2555 * 2556 0 2557 0 2558 +00:00 2559 2560 2562 2563 once-every-six-hours 2564 2565 * 2566 * 2567 * 2568 0 2569 6 2570 12 2571 18 2572 0 2573 0 2574 2575 3600000 2576 2578 2579 dec-31-11:00 2580 2581 december 2582 31 2583 * 2584 11 2585 00 2586 00 2587 2588 2590 2591 jan-01-15:00 2592 2593 january 2594 1 2595 * 2596 15 2597 00 2598 00 2599 2600 2602 2603 startup 2604 2605 2606 12345 2607 2609 2610 controller-lost 2611 2612 2614 2615 controller-connected 2616 2617 2618 12345 2619 2620 2621 2622 2624 Appendix H. Example Configuration (JSON) 2626 { 2627 "ietf-lmap-control:lmap": { 2628 "agent": { 2629 "agent-id": "550e8400-e29b-41d4-a716-446655440000", 2630 "device-id": "urn:dev:mac:0024befffe804ff1", 2631 "group-id": "network measurement at the north-pole", 2632 "report-agent-id": true 2633 }, 2634 "tasks": { 2635 "task": [ 2636 { 2637 "name": "iperf-server", 2638 "program": "/usr/bin/iperf", 2639 "option": [ 2640 { 2641 "id": "server", 2642 "name": "-s" 2643 } 2644 ], 2645 "tag": [ 2646 "passive", 2647 "iperf" 2648 ] 2649 }, 2650 { 2651 "name": "iperf-client", 2652 "program": "/usr/bin/iperf", 2653 "option": [ 2654 { 2655 "id": "client", 2656 "name": "-c" 2657 } 2658 ], 2659 "tag": [ 2660 "active", 2661 "iperf" 2662 ] 2663 }, 2664 { 2665 "name": "lmap-reporting-task", 2666 "program": "/usr/bin/lmap-reporter", 2667 "option": [ 2668 { 2669 "id": "collector-uri", 2670 "value": "https://example.com/restconf/operations/ietf-lmap-report:report" 2671 } 2672 ] 2673 }, 2674 { 2675 "name": "fcc-measurement-suite", 2676 "program": "/usr/bin/fcc-suite" 2677 }, 2678 { 2679 "name": "ippm-udp-latency-client", 2680 "program": "/usr/bin/ippm-udp-latency", 2681 "metric": [ 2682 { 2683 "uri": "urn:example:what?", 2684 "role": [ 2685 "client" 2686 ] 2687 } 2688 ], 2689 "tag": [ 2690 "active" 2691 ] 2692 } 2693 ] 2694 }, 2695 "schedules": { 2696 "schedule": [ 2697 { 2698 "name": "fcc-campain-2016", 2699 "start": "fcc-hourly-sep-2016", 2700 "duration": 600, 2701 "execution-mode": "pipelined", 2702 "action": [ 2703 { 2704 "name": "fcc-measurement", 2705 "task": "fcc-measurement-suite" 2706 }, 2707 { 2708 "name": "fcc-report", 2709 "task": "lmap-reporting-task", 2710 "option": [ 2711 { 2712 "id": "collector-uri", 2713 "value": "https://fcc.example.com/restconf/operations/ietf-lmap-report:report" 2714 } 2715 ] 2716 } 2717 ] 2718 }, 2719 { 2720 "name": "iperf-hourly", 2721 "start": "hourly", 2722 "execution-mode": "sequential", 2723 "action": [ 2724 { 2725 "name": "iperf-hourly-mlab1", 2726 "task": "iperf-client", 2727 "option": [ 2728 { 2729 "id": "mlab1", 2730 "value": "mlab1.example.com" 2731 } 2732 ] 2733 }, 2734 { 2735 "name": "iperf-hourly-mlab2", 2736 "task": "iperf-client", 2737 "option": [ 2738 { 2739 "id": "mlab2", 2740 "value": "mlab2.example.com" 2741 } 2742 ], 2743 "destination": [ 2744 "report-collector", 2745 "report-shadow-collector" 2746 ] 2747 } 2748 ] 2749 }, 2750 { 2751 "name": "startup", 2752 "start": "startup", 2753 "action": [ 2754 { 2755 "name": "iperf-server", 2756 "task": "iperf-server" 2757 } 2758 ] 2759 }, 2760 { 2761 "name": "report-collector", 2762 "start": "once-every-six-hours", 2763 "action": [ 2764 { 2765 "name": "report-action", 2766 "task": "lmap-reporting-task", 2767 "option": [ 2768 { 2769 "id": "collector-uri", 2770 "value": "https://collector.example.com/restconf/operations/ietf-lmap-report:report" 2771 } 2772 ] 2773 } 2775 ] 2776 }, 2777 { 2778 "name": "report-shadow-collector", 2779 "start": "daily", 2780 "action": [ 2781 { 2782 "name": "report-action", 2783 "task": "lmap-reporting-task", 2784 "option": [ 2785 { 2786 "id": "collector-uri", 2787 "value": "https://shadow.example.com/restconf/operations/ietf-lmap-report:report" 2788 } 2789 ] 2790 } 2791 ] 2792 }, 2793 { 2794 "name": "ippm-udp-latency", 2795 "start": "hourly", 2796 "execution-mode": "sequential", 2797 "action": [ 2798 { 2799 "name": "ippm-udp-latency", 2800 "task": "ippm-udp-latency-client", 2801 "parameters": { 2802 "src-ip": "192.0.2.1", 2803 "src-port": 54321, 2804 "dst-ip": "192.0.2.2", 2805 "dst-port": 12345, 2806 "poisson-lambda": "42" 2807 } 2808 }, 2809 { 2810 "name": "ippm-udp-latency-report", 2811 "task": "lmap-reporting-task", 2812 "option": [ 2813 { 2814 "id": "collector-uri", 2815 "value": "https://ippm.example.com/restconf/operations/ietf-lmap-report:report" 2816 } 2817 ] 2818 } 2819 ] 2820 } 2821 ] 2822 }, 2823 "suppressions": { 2824 "suppression": [ 2825 { 2826 "name": "orphaned", 2827 "start": "controller-lost", 2828 "end": "controller-connected", 2829 "match": [ 2830 "*" 2831 ] 2832 }, 2833 { 2834 "name": "new-year-evening", 2835 "start": "dec-31-11:00", 2836 "end": "jan-01-15:00", 2837 "match": [ 2838 "active" 2839 ] 2840 } 2841 ] 2842 }, 2843 "events": { 2844 "event": [ 2845 { 2846 "name": "fcc-hourly-sep-2016", 2847 "periodic": { 2848 "interval": 3600000, 2849 "start": "2016-09-01T00:00:00+00:00", 2850 "end": "2016-10-01T00:00:00+00:00" 2851 }, 2852 "random-spread": 300000 2853 }, 2854 { 2855 "name": "monthly", 2856 "calendar": { 2857 "month": [ 2858 "*" 2859 ], 2860 "day-of-week": [ 2861 "*" 2862 ], 2863 "day-of-month": [ 2864 1 2865 ], 2866 "hour": [ 2867 0 2868 ], 2869 "minute": [ 2870 0 2872 ], 2873 "second": [ 2874 0 2875 ], 2876 "timezone-offset": "+00:00" 2877 } 2878 }, 2879 { 2880 "name": "weekly", 2881 "calendar": { 2882 "month": [ 2883 "*" 2884 ], 2885 "day-of-week": [ 2886 "monday" 2887 ], 2888 "day-of-month": [ 2889 "*" 2890 ], 2891 "hour": [ 2892 0 2893 ], 2894 "minute": [ 2895 0 2896 ], 2897 "second": [ 2898 0 2899 ], 2900 "timezone-offset": "+00:00" 2901 } 2902 }, 2903 { 2904 "name": "daily", 2905 "calendar": { 2906 "month": [ 2907 "*" 2908 ], 2909 "day-of-week": [ 2910 "*" 2911 ], 2912 "day-of-month": [ 2913 "*" 2914 ], 2915 "hour": [ 2916 0 2917 ], 2918 "minute": [ 2919 0 2921 ], 2922 "second": [ 2923 0 2924 ], 2925 "timezone-offset": "+00:00" 2926 } 2927 }, 2928 { 2929 "name": "hourly", 2930 "calendar": { 2931 "month": [ 2932 "*" 2933 ], 2934 "day-of-month": [ 2935 "*" 2936 ], 2937 "day-of-week": [ 2938 "*" 2939 ], 2940 "hour": [ 2941 "*" 2942 ], 2943 "minute": [ 2944 0 2945 ], 2946 "second": [ 2947 0 2948 ], 2949 "timezone-offset": "+00:00" 2950 } 2951 }, 2952 { 2953 "name": "once-every-six-hours", 2954 "calendar": { 2955 "month": [ 2956 "*" 2957 ], 2958 "day-of-month": [ 2959 "*" 2960 ], 2961 "day-of-week": [ 2962 "*" 2963 ], 2964 "hour": [ 2965 0, 2966 6, 2967 12, 2968 18 2970 ], 2971 "minute": [ 2972 0 2973 ], 2974 "second": [ 2975 0 2976 ] 2977 }, 2978 "random-spread": 3600000 2979 }, 2980 { 2981 "name": "dec-31-11:00", 2982 "calendar": { 2983 "month": [ 2984 "december" 2985 ], 2986 "day-of-month": [ 2987 31 2988 ], 2989 "day-of-week": [ 2990 "*" 2991 ], 2992 "hour": [ 2993 11 2994 ], 2995 "minute": [ 2996 00 2997 ], 2998 "second": [ 2999 00 3000 ] 3001 } 3002 }, 3003 { 3004 "name": "jan-01-15:00", 3005 "calendar": { 3006 "month": [ 3007 "january" 3008 ], 3009 "day-of-month": [ 3010 1 3011 ], 3012 "day-of-week": [ 3013 "*" 3014 ], 3015 "hour": [ 3016 15 3017 ], 3018 "minute": [ 3019 00 3020 ], 3021 "second": [ 3022 00 3023 ] 3024 } 3025 }, 3026 { 3027 "name": "startup", 3028 "startup": [null], 3029 "random-spread": 12345 3030 }, 3031 { 3032 "name": "controller-lost", 3033 "controller-lost": [null] 3034 }, 3035 { 3036 "name": "controller-connected", 3037 "controller-connected": [null], 3038 "random-spread": 12345 3039 } 3040 ] 3041 } 3042 } 3043 } 3045 Appendix I. Example State (XML) 3047 3048 3050 3051 550e8400-e29b-41d4-a716-446655440000 3052 urn:dev:mac:0024befffe804ff1 3053 ACME home router 3054 OpenWrt version 10.03.1 3055 Measurement Agent Daemon (MAD) 4.2 3056 2015-04-10T17:24:42+02:00 3057 3059 3060 3061 udp-latency-measurement 3062 3063 urn:.... 3064 source 3065 target 3066 3067 3069 3070 icmp-latency-measurement 3071 3072 urn:.... 3073 3074 3076 3077 iperf 3078 iperf 3079 3081 3082 lmap-reporting-task 3083 lmap-reportd 3084 3085 3087 3088 3089 hourly-schedule 3090 enabled 3091 2015-01-23T12:00:00+01:00 3092 3093 icmp-latency-hourly 3094 enabled 3095 2015-01-23T12:00:00+01:00 3096 2015-01-23T12:00:01+01:00 3097 0 3098 OK 3099 2015-01-23T03:00:00+01:00 3100 42 3101 connection timed out 3102 3103 3104 udp-latency-weekdays-hourly 3105 2015-01-23T12:00:01+01:00 3106 2015-01-23T12:00:02+01:00 3107 0 3108 OK 3109 2015-01-23T03:00:00+01:00 3110 42 3111 connection timed out 3113 3114 3115 3116 3117 3119 Appendix J. Example State (JSON) 3121 { 3122 "ietf-lmap-control:lmap-state": { 3123 "agent": { 3124 "agent-id": "550e8400-e29b-41d4-a716-446655440000", 3125 "device-id": "urn:dev:mac:0024befffe804ff1", 3126 "hardware": "ACME home router", 3127 "firmware": "OpenWrt version 10.03.1", 3128 "version": "Measurement Agent Daemon (MAD) 4.2", 3129 "last-started": "2015-04-10T17:24:42+02:00" 3130 }, 3131 "tasks": { 3132 "task": [ 3133 { 3134 "name": "udp-latency-measurement", 3135 "metric": [ 3136 { 3137 "uri": "urn:....", 3138 "role": [ 3139 "source", 3140 "target" 3141 ] 3142 } 3143 ] 3144 }, 3145 { 3146 "name": "icmp-latency-measurement", 3147 "metric": [ 3148 { 3149 "uri": "urn:...." 3150 } 3151 ] 3152 }, 3153 { 3154 "name": "iperf", 3155 "program": "iperf" 3156 }, 3157 { 3158 "name": "lmap-reporting-task", 3159 "program": "lmap-reportd" 3160 } 3161 ] 3162 }, 3163 "schedules": { 3164 "schedule": [ 3165 { 3166 "name": "hourly-schedule", 3167 "state": "enabled", 3168 "last-invocation": "2015-01-23T12:00:00+01:00", 3169 "action": [ 3170 { 3171 "name": "icmp-latency-hourly", 3172 "state": "enabled", 3173 "last-invocation": "2015-01-23T12:00:00+01:00", 3174 "last-completion": "2015-01-23T12:00:01+01:00", 3175 "last-status": 0, 3176 "last-message": "OK", 3177 "last-failed-completion": "2015-01-23T03:00:00+01:00", 3178 "last-failed-status": 42, 3179 "last-failed-message": "connection timed out" 3180 }, 3181 { 3182 "name": "udp-latency-weekdays-hourly", 3183 "last-invocation": "2015-01-23T12:00:01+01:00", 3184 "last-completion": "2015-01-23T12:00:02+01:00", 3185 "last-status": 0, 3186 "last-message": "OK", 3187 "last-failed-completion": "2015-01-23T03:00:00+01:00", 3188 "last-failed-status": 42, 3189 "last-failed-message": "connection timed out" 3190 } 3191 ] 3192 } 3193 ] 3194 } 3195 } 3196 } 3198 Appendix K. Example Report (XML) 3200 3201 3203 3204 2015-10-28T13:27:42+02:00 3205 550e8400-e29b-41d4-a716-446655440000 3206 wireless measurement at the north-pole 3207 3208 pinger 3209 fping 3210 fping 3211 2016-03-21T10:48:55+01:00 3212 2016-03-21T10:48:57+01:00 3213 3217 3221 3226 3230 3234 3238 3239 target 3240 ip 3241 rtt-1 3242 rtt-2 3243 rtt-3 3244 rtt-4 3245 rtt-5 3246 3247 www.example.org 3248 192.0.2.1 3249 14.15 3250 14.14 3251 14.09 3252 14.17 3253 14.51 3254 3255 3256 mail.example.org 3257 192.0.2.2 3258 12.24 3259 11.99 3260 12.49 3261 11.87 3262 12.45 3263 3264
3265 3266 3267 3269 Appendix L. Example Report (JSON) 3271 { 3272 "report": { 3273 "date": "2015-10-28T13:27:42+02:00", 3274 "agent-id": "550e8400-e29b-41d4-a716-446655440000", 3275 "group-id": "wireless measurement at the north-pole", 3276 "result": [ 3277 { 3278 "schedule-name": "pinger", 3279 "action-name": "fping", 3280 "task-name": "fping", 3281 "start": "2016-03-21T10:48:55+01:00", 3282 "start": "2016-03-21T10:48:57+01:00", 3283 "option": [ 3284 { 3285 "id": "display-address", 3286 "name": "-A" 3287 }, 3288 { 3289 "id": "display-DNS-lookup", 3290 "name": "-d" 3291 }, 3292 { 3293 "id": "number-of-packets", 3294 "name": "-C", 3295 "value": "5" 3296 }, 3297 { 3298 "id": "quiet", 3299 "name": "-q" 3300 }, 3301 { 3302 "id": "www.example.org", 3303 "name": "www.example.org" 3304 }, 3305 { 3306 "id": "mail.example.com", 3307 "name": "mail.example.com" 3308 } 3309 ], 3310 "table": [ 3311 { 3312 "column": [ 3313 "target", 3314 "ip", 3315 "rtt-1", 3316 "rtt-2", 3317 "rtt-3", 3318 "rtt-4", 3319 "rtt-5" 3320 ], 3321 "row": [ 3322 { 3323 "value": [ 3324 "www.example.org", 3325 "192.0.2.1", 3326 "14.15", 3327 "14.14", 3328 "14.09", 3329 "14.17", 3330 "14.51" 3331 ] 3332 }, 3333 { 3334 "value": [ 3335 "mail.example.org", 3336 "192.0.2.2", 3337 "12.24", 3338 "11.99", 3339 "12.49", 3340 "11.87", 3341 "12.45" 3342 ] 3343 } 3344 ] 3345 } 3346 ] 3348 } 3349 ] 3350 } 3351 } 3353 Authors' Addresses 3355 Juergen Schoenwaelder 3356 Jacobs University Bremen 3358 Email: j.schoenwaelder@jacobs-university.de 3360 Vaibhav Bajpai 3361 Jacobs University Bremen 3363 Email: v.bajpai@jacobs-university.de