idnits 2.17.1 draft-ietf-lmap-yang-00.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 2 instances of too long lines in the document, the longest one being 33 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 164 has weird spacing: '...nterval uin...' == Line 196 has weird spacing: '...started yan...' == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (April 10, 2015) is 3275 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) ** Obsolete normative reference: RFC 7223 (Obsoleted by RFC 8343) == Outdated reference: A later version (-14) exists of draft-ietf-lmap-framework-12 == Outdated reference: A later version (-18) exists of draft-ietf-lmap-information-model-05 Summary: 2 errors (**), 0 flaws (~~), 6 warnings (==), 1 comment (--). 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: October 12, 2015 April 10, 2015 7 A YANG Data Model for LMAP Measurement Agents 8 draft-ietf-lmap-yang-00.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 October 12, 2015. 33 Copyright Notice 35 Copyright (c) 2015 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 . . . . . . . . . . . . . . . . . . . . . . 2 53 2. Data Model Overview . . . . . . . . . . . . . . . . . . . . . 3 54 3. Relationship to the Information Model . . . . . . . . . . . . 6 55 4. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 7 56 5. Security Considerations . . . . . . . . . . . . . . . . . . . 29 57 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 58 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 30 59 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 30 60 8.1. Normative References . . . . . . . . . . . . . . . . . . 30 61 8.2. Informative References . . . . . . . . . . . . . . . . . 30 62 Appendix A. Example Configuration (XML) . . . . . . . . . . . . 31 63 Appendix B. Example Configuration (JSON) . . . . . . . . . . . . 35 64 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 40 66 1. Introduction 68 This document defines a data model for Large-Scale Measurement 69 Platforms (LMAP) [I-D.ietf-lmap-framework]. The data model is 70 defined using the YANG [RFC6020] data modeling language. It aims to 71 be consistent with the LMAP Information Model 72 [I-D.ietf-lmap-information-model]. 74 1.1. Terminology 76 This document uses the LMAP terminology defined in 77 [I-D.ietf-lmap-framework]. 79 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 80 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 81 document are to be interpreted as described in [RFC2119]. 83 1.2. Tree Diagrams 85 A simplified graphical representation of the data model is used in 86 this document. The meaning of the symbols in these diagrams is as 87 follows: 89 o Brackets "[" and "]" enclose list keys. 91 o Abbreviations before data node names: "rw" means configuration 92 (read-write), and "ro" means state data (read-only). 94 o Symbols after data node names: "?" means an optional node, "!" 95 means a presence container, and "*" denotes a list and leaf-list. 97 o Parentheses enclose choice and case nodes, and case nodes are also 98 marked with a colon (":"). 100 o Ellipsis ("...") stands for contents of subtrees that are not 101 shown. 103 2. Data Model Overview 105 The tree diagram below shows the structure of the configuration 106 model. 108 module: ietf-lmap-control 109 +--rw lmap 110 +--rw agent 111 | +--rw agent-id? yang:uuid 112 | +--rw device-id? inet:uri 113 | +--rw credentials? string 114 | +--rw group-id? string 115 | +--rw report-agent-id? boolean 116 | +--rw controller-lost-timeout? uint32 117 +--rw schedules 118 | +--rw schedule* [name] 119 | +--rw name string 120 | +--rw action* [name] 121 | | +--rw name string 122 | | +--rw task -> /lmap/tasks/task/name 123 | | +--rw option* [name] 124 | | | +--rw name string 125 | | | +--rw value? string 126 | | +--rw destination* [name] 127 | | +--rw name string 128 | | +--rw output* uint16 129 | | +--rw schedule -> /lmap/schedules/schedule/name 130 | | +--rw action -> /lmap/schedules/schedule[name = current()/../schedule]/action/name 131 | +--rw timing -> /lmap/timings/timing/name 132 +--rw suppression 133 | +--rw enabled? boolean 134 | +--rw stop-running? boolean 135 | +--rw start? yang:date-and-time 136 | +--rw end? yang:date-and-time 137 | +--rw task* -> /lmap/tasks/task/name 138 | +--rw schedule* -> /lmap/schedules/schedule/name 139 +--rw channels 140 | +--rw channel* [name] 141 | +--rw name string 142 | +--rw target? inet:uri 143 | +--rw credentials? string 144 | +--rw interface? -> /if:interfaces/interface/name 145 +--rw tasks 146 | +--rw task* [name] 147 | +--rw name string 148 | +--rw (task-identification) 149 | | +--:(registry) 150 | | | +--rw registry? inet:uri 151 | | +--:(program) 152 | | +--rw program? string 153 | +--rw option* [name] 154 | | +--rw name string 155 | | +--rw value? string 156 | +--rw tag* string 157 | +--rw suppress-by-default? boolean 158 +--rw timings 159 +--rw timing* [name] 160 +--rw name string 161 +--rw (timing-type)? 162 | +--:(periodic) 163 | | +--rw periodic 164 | | +--rw interval uint32 165 | | +--rw start? yang:date-and-time 166 | | +--rw end? yang:date-and-time 167 | +--:(calendar) 168 | | +--rw calendar 169 | | +--rw month* union 170 | | +--rw weekday* union 171 | | +--rw day-of-month* union 172 | | +--rw hour* union 173 | | +--rw minute* union 174 | | +--rw second* union 175 | | +--rw timezone-offset? timezone-offset 176 | | +--rw start? yang:date-and-time 177 | | +--rw end? yang:date-and-time 178 | +--:(one-off) 179 | | +--rw one-off-time yang:date-and-time 180 | +--:(immediate) 181 | | +--rw immediate empty 182 | +--:(startup) 183 | +--rw startup empty 184 +--rw random-spread? int32 186 The tree diagram below shows the structure of the state model. 188 module: ietf-lmap-control 189 +--ro lmap-state 190 +--ro agent 191 | +--ro agent-id yang:uuid 192 | +--ro device-id inet:uri 193 | +--ro hardware string 194 | +--ro firmware string 195 | +--ro version string 196 | +--ro last-started yang:date-and-time 197 +--ro tasks 198 +--ro task* [name] 199 +--ro name string 200 +--ro (task-identification) 201 | +--:(registry) 202 | | +--ro registry? inet:uri 203 | +--:(program) 204 | +--ro program? string 205 +--ro last-completion? yang:date-and-time 206 +--ro last-status? status-code 207 +--ro last-message? string 208 +--ro last-failed-completion? yang:date-and-time 209 +--ro last-failed-status? status-code 210 +--ro last-failed-message? string 212 The tree diagram below shows the structure of the notification 213 (reporting) model. 215 module: ietf-lmap-report 216 notifications: 217 +---n report 218 +--ro date yang:date-and-time 219 +--ro agent-id? yang:uuid 220 +--ro group-id? string 221 +--ro task* [name] 222 | +--ro name string 223 | +--ro (task-identification) 224 | | +--:(registry) 225 | | | +--ro registry? inet:uri 226 | | +--:(program) 227 | | +--ro program? string 228 | +--ro option* [name] 229 | | +--ro name string 230 | | +--ro value? string 231 | +--ro tag* string 232 | +--ro suppress-by-default? boolean 233 +--ro header 234 | +--ro column* string 235 +--ro row* 236 +--ro start yang:date-and-time 237 +--ro end? yang:date-and-time 238 +--ro conflict* string 239 +--ro value* string 241 3. Relationship to the Information Model 243 The LMAP information model [I-D.ietf-lmap-information-model] is 244 devided into six sections. They are mapped into the YANG data model 245 as explained below: 247 o Pre-Configuration Information: This is not modeled explicitly 248 since it is a subset of the configuration information. 250 o Configuration Information: This is modeled in the /lmap/agent 251 subtree and the /lmap/schedules, /lmap/tasks, and /lmap/channels 252 subtrees described below. Some items have been left out because 253 they are expected to be dealt with by the underlying protocol. 255 o Instruction Information: This is modeled in the /lmap/suppression 256 subtree and the /lmap/schedules, /lmap/tasks, and /lmap/channels 257 subtrees described below. 259 o Logging Information: Some of the logging information, in 260 particular 'success/failure/warning messages in response to 261 information updates from the Controller', will be handled by the 262 protocol used to manipulate the lmap specific configuration. 263 [[CREF1: It needs to be discussed whether we can rely on informal 264 syslog messages that can be accessed via protocols such RFC 5277 265 or whether we want to define specific notifications in the YANG 266 data model. --JS]] 268 o Capability and Status Information: Some of the status information 269 is modeled in the /lmap-state/agent subtree. Information about 270 network interfaces can be obtained from the interfaces YANG data 271 model [RFC7223]. The list of supported tasks is modeled in the 272 /lmap-state/tasks subtree including information about the last 273 execution and the last failed execution. 275 o Reporting Information: This is modeled by the report notification. 277 These six sections are build on the following common information 278 objects: 280 o Schedules: This is modeled in the /lmap/schedules subtree. 282 o Channels: This is modeled in the /lmap/channels subtree. 284 o Task Configurations: This is modeled in the /lmap/tasks subtree. 286 o Timing Information: This is modeled in the /lmap/timings subtree. 288 4. YANG Modules 290 The modules import definitions from [RFC6991] and [RFC7223]. 292 file "ietf-lmap-control@2015-04-10.yang" 293 module ietf-lmap-control { 295 namespace "urn:ietf:params:xml:ns:yang:ietf-lmap-control"; 296 prefix "lmapc"; 298 import ietf-yang-types { 299 prefix yang; 300 } 301 import ietf-inet-types { 302 prefix inet; 303 } 304 import ietf-interfaces { 305 prefix if; 306 } 308 organization 309 "IETF Large-Scale Measurement Platforms Working Group"; 311 contact 312 "WG Web: 313 WG List: 315 Editor: Juergen Schoenwaelder 316 318 Editor: Vaibhav Bajpai 319 "; 321 description 322 "This module defines a data model for controlling measurement 323 agents that are part of a Large-Scale Measurement Platform 324 (LMAP)."; 326 revision "2015-04-10" { 327 description 328 "Initial version"; 329 reference 330 "RFC XXX: A YANG Data Model for LMAP Measurement Agents"; 331 } 333 /* 334 * Typedefs 335 */ 337 typedef weekday { 338 type enumeration { 339 enum sunday { 340 value 0; 341 description "Sunday of the week"; 342 } 343 enum monday { 344 value 1; 345 description "Monday of the week"; 346 } 347 enum tuesday { 348 value 2; 349 description "Tuesday of the week"; 350 } 351 enum wednesday { 352 value 3; 353 description "Wednesday of the week"; 354 } 355 enum thursday { 356 value 4; 357 description "Thursday of the week"; 358 } 359 enum friday { 360 value 5; 361 description "Friday of the week"; 362 } 363 enum saturday { 364 value 6; 365 description "Saturday of the week"; 366 } 367 } 368 description 369 "A type modeling the weekdays in the Greco-Roman 370 tradition."; 371 } 373 typedef month { 374 type enumeration { 375 enum january { 376 value 1; 377 description "January of the Julian and Gregorian calendar"; 378 } 379 enum february { 380 value 2; 381 description "February of the Julian and Gregorian calendar"; 382 } 383 enum march { 384 value 3; 385 description "March of the Julian and Gregorian calendar"; 386 } 387 enum april { 388 value 4; 389 description "April of the Julian and Gregorian calendar"; 390 } 391 enum may { 392 value 5; 393 description "May of the Julian and Gregorian calendar"; 394 } 395 enum june { 396 value 6; 397 description "June of the Julian and Gregorian calendar"; 398 } 399 enum july { 400 value 7; 401 description "July of the Julian and Gregorian calendar"; 402 } 403 enum august { 404 value 8; 405 description "August of the Julian and Gregorian calendar"; 406 } 407 enum september { 408 value 9; 409 description "September of the Julian and Gregorian calendar"; 410 } 411 enum october { 412 value 10; 413 description "October of the Julian and Gregorian calendar"; 414 } 415 enum november { 416 value 11; 417 description "November of the Julian and Gregorian calendar"; 418 } 419 enum december { 420 value 12; 421 description "December of the Julian and Gregorian calendar"; 422 } 423 } 424 description 425 "A type modeling the month in the Julian and Gregorian 426 tradition."; 427 } 429 typedef wildcard { 430 type string { pattern '\*'; } 431 description 432 "A wildcard for calendar scheduling entries."; 433 } 435 typedef status-code { 436 type int32; 437 description 438 "A status code returned by the execution of a task. Note that 439 the actual range is implementation dependent but it should 440 be portable to use values in the range 0..127. By convention, 441 0 indicates successful termination."; 442 } 444 typedef timezone-offset { 445 type string { 446 pattern 'Z|[\+\-]\d{2}:\d{2}'; 447 } 448 description 449 "A timezone-offset as it is use in the yang:date-and-time 450 type. The value Z is equivalent to +00:00. The value -00:00 451 indicates and unknown time-offset."; 452 } 453 /* 454 * Groupings 455 */ 457 grouping timing-start-end-grouping { 458 description 459 "A grouping that provides start and end times for 460 timing objects."; 461 leaf start { 462 type yang:date-and-time; 463 description 464 "The date and time when the timing object 465 starts to create triggers."; 466 } 467 leaf end { 468 type yang:date-and-time; 469 description 470 "The date and time when the timing object 471 stops to create triggers. 473 It is generally a good idea to always configure 474 an end time and to refresh the configuration 475 of timing object as needed to ensure that agents 476 that loose connectivity to their controller 477 do not continue their tasks forever."; 478 } 479 } 481 grouping task-options-grouping { 482 description 483 "A list of options of a task. Each option is a name/value 484 pair (where the value may be absent)."; 486 list option { 487 key "name"; 488 ordered-by user; 490 description 491 "A list of options passed to the task. It is a list of 492 key / value pairs and may be used to model options. 493 Options may be used to identify the role of a task 494 or to pass a channel name to a task."; 496 // XXX This is kind of broken since making the option name 497 // XXX a key means that a certain option may only appear once. 498 // XXX This is not workable since some tests require a list of 499 // XXX targets. Turning this into a leaf-list of args also 500 // XXX does not work since YANG requires leaf-list values to 501 // XXX be unique. Oops. 503 leaf name { 504 type string; 505 description 506 "The name of the option."; 507 } 509 leaf value { 510 type string; 511 description 512 "The value of the option."; 513 } 514 } 515 } 517 grouping task-grouping { 518 description 519 "A grouping that defines the configuration of a task."; 521 list task { 522 key name; 523 description 524 "The list of tasks configured on the LMAP agent."; 526 leaf name { 527 type string; 528 description 529 "The unique name of a task."; 530 } 532 choice task-identification { 533 mandatory true; 534 description 535 "Information that identifies the task."; 537 leaf registry { 538 type inet:uri; 539 description 540 "The registry entry identifying the configured task."; 541 } 543 leaf program { 544 type string; 545 description 546 "The (local) program to invoke in order to execute 547 the task."; 548 } 550 } 552 uses task-options-grouping { 553 description 554 "The list of task specific options."; 555 } 557 leaf-list tag { 558 type string; 559 description 560 "A tag contains additional information that is passed 561 with the result record to the collector. A tag can be 562 used to carry the Measurement Cycle ID."; 563 } 565 leaf suppress-by-default { 566 type boolean; 567 default true; 568 description 569 "Indicates whether the task will be suppressed by 570 a default supression."; 571 } 572 } 573 } 575 /* 576 * Configuration data nodes 577 */ 579 container lmap { 580 description 581 "Configuration of the LMAP agent."; 583 /* 584 * Common Information Objects: Configuration 585 */ 587 container agent { 588 description 589 "Configuration of parameters affecting the whole 590 measurement agent."; 592 leaf agent-id { 593 type yang:uuid; 594 description 595 "The agent-id identifies a measurement agent with 596 a very low probability of collision. In certain 597 deployments, the agent-id may be considered 598 sensitive and hence this object is optional."; 599 } 601 leaf device-id { 602 type inet:uri; 603 description 604 "The device-id identifies a property of the 605 device running the measurement agent. In certain 606 deployments, the device-id may be considered 607 sensitive and hence this object is optional."; 608 } 610 leaf credentials { 611 type string; 612 description 613 "The credentials of the agent."; 614 // XXX: This is way too simplistic. Credentials are 615 // specific to the authentication mechanism used 616 // by a protocol. Hence, this needs to be a far 617 // more complex and extensible choice or it might 618 // not be needed since the protocol data models 619 // already cover it. 620 } 622 leaf group-id { 623 type string; 624 description 625 "The group-id identifies a group of measurement 626 agents. In certain deployments, the group-id 627 may be considered less sensitive than the 628 agent-id."; 629 } 631 leaf report-agent-id { 632 type boolean; 633 default false; 634 // XXX: write a must expression that requires 635 // group-id to be configured when this is true? 636 description 637 "The 'report-agent-id' controls whether the 638 'agent-id' is reported to collectors if the 639 'group-id' is configured. If the 'group-id' 640 is not configured, the agent-id is always 641 reported."; 642 } 644 leaf controller-lost-timeout { 645 type uint32; 646 units ""; 647 description 648 "A timer is started after each successful contact 649 with a controller. When the timer reaches the 650 controller-lost-timeout, all schedules will be 651 disabled."; 652 } 653 } 655 /* 656 * Common Information Objects: Schedules 657 */ 659 container schedules { 660 description 661 "Configuration of LMAP schedules. Schedules control with 662 tasks are executed by the LMAP implementation."; 664 list schedule { 665 key name; 666 description 667 "Configuration of a particular schedule."; 669 leaf name { 670 type string; 671 description 672 "The locally-unique, administratively assigned name for 673 this scheduled task."; 674 } 676 list action { 677 key name; 678 description 679 "An action describes a task that is invoked by the 680 schedule. Multiple actions are invoked sequentially."; 682 leaf name { 683 type string; 684 description 685 "The unique identifier for this action."; 686 } 688 leaf task { 689 type leafref { 690 path "/lmap/tasks/task/name"; 691 } 692 mandatory true; 693 description 694 "The tasks invoked by this action."; 695 } 697 uses task-options-grouping { 698 description 699 "The list of action specific options that are 700 appended to the list of task specific options."; 701 } 703 list destination { 704 key "name"; 705 description 706 "A destination receives information from the task 707 associated with this action. A queue is internally 708 used to pass the information to another (scheduled) 709 action."; 711 leaf name { 712 type string; 713 description 714 "The name of this destination (queue) that passes 715 information to another (scheduled) action."; 716 } 718 leaf-list output { 719 type uint16; 720 description 721 "The list of outputs of a task directed to another 722 (scheduled) action. If no output is specified, 723 then all output is directed to another (scheduled) 724 action."; 725 } 727 leaf schedule { 728 type leafref { 729 path "/lmap/schedules/schedule/name"; 730 } 731 mandatory true; 732 description 733 "The schedule of the (scheduled) action receiving 734 the output."; 735 } 737 leaf action { 738 type leafref { 739 path "/lmap/schedules/schedule" 740 + "[name = current()/../schedule]" 741 + "/action/name"; 743 } 744 mandatory true; 745 description 746 "The (scheduled) action receiving the output (the 747 destination consuming the data from the queue)."; 748 } 749 } 750 } 752 leaf timing { 753 type leafref { 754 path "/lmap/timings/timing/name"; 755 } 756 mandatory true; 757 description 758 "The timing source controlling the start of the scheduled 759 tasks."; 760 } 761 } 762 } 764 /* 765 * Suppression 766 */ 768 container suppression { 769 description 770 "Suppression information to prevent schedules to start 771 certain tasks."; 773 leaf enabled { 774 type boolean; 775 default false; 776 description 777 "Setting 'enabled' to true will suppress all tasks for 778 which suppress-by-default is true."; 779 } 781 leaf stop-running { 782 type boolean; 783 default false; 784 description 785 "Setting 'stop-running' to true will cause running 786 tasks to be terminated if suppression is enabled 787 (the 'enabled' leaf is set to true). Otherwise, 788 running tasks will not be affected if suppression 789 is enabled."; 790 } 791 leaf start { 792 type yang:date-and-time; 793 description 794 "The date and time when supression starts to 795 become effective. If not present, supression 796 becomes effective immeditately when 'enabled' 797 is set to true."; 798 } 800 leaf end { 801 type yang:date-and-time; 802 description 803 "The date and time when supression stops to 804 be effective. If not present, supression 805 continues indefinite until 'enabled' is set 806 to false."; 807 } 809 leaf-list task { 810 type leafref { 811 path "/lmap/tasks/task/name"; 812 } 813 description 814 "A specific task to suppress. If no tasks are 815 listed, then all tasks will be suppressed."; 816 } 818 leaf-list schedule { 819 type leafref { 820 path "/lmap/schedules/schedule/name"; 821 } 822 description 823 "A specific schedule to suppress. If no schedules 824 are listed, then all schedules will be suppressed."; 825 } 827 } 829 /* 830 * Common Information Objects: Channels 831 */ 833 container channels { 834 description 835 "A channel describes properties of an LMAP control or 836 reporting channel."; 838 list channel { 839 key name; 840 description 841 "The list of channels configured on the LMAP agent."; 843 leaf name { 844 type string; 845 description 846 "The unique name of a channel."; 847 } 849 leaf target { 850 type inet:uri; 851 description 852 "The remote endpoint of the channel."; 853 } 855 leaf credentials { 856 type string; 857 description 858 "The credentials of the channel."; 859 // XXX: This is way too simplistic. Credentials are 860 // specific to the authentication mechanism used 861 // by a protocol. Hence, this needs to be a far 862 // more complex and extensible choice. 863 } 865 leaf interface { 866 type leafref { 867 path "/if:interfaces/if:interface/if:name"; 868 } 869 description 870 "The local interface used to reach the remote 871 endpoint of the channel. If not present, the 872 system will select a suitable interface."; 873 } 874 } 875 } 877 /* 878 * Common Information Objects: Task Configurations 879 */ 881 container tasks { 882 description 883 "Configuration of LMAP tasks."; 885 uses task-grouping; 886 } 887 /* 888 * Common Information Objects: Timing Information 889 */ 891 container timings { 892 description 893 "Configuration of LMAP timings. 895 Implementations may be forced to delay acting 896 upon triggers in the face of local constraints. 897 A task triggered therefore not rely on the accuracy 898 provided by the scheduler implementation."; 900 list timing { 901 key name; 902 description 903 "The list of timings configured on the LMAP agent."; 905 leaf name { 906 type string; 907 description 908 "The unique name of a timing."; 909 } 911 choice timing-type { 912 description 913 "Different types of timing objects are handled by 914 different branches of this choices."; 916 case periodic { 917 container periodic { 918 description 919 "A periodic timing object triggers periodically 920 driven by a regular interval."; 922 leaf interval { 923 type uint32; 924 units "milliseconds"; 925 mandatory true; 926 description 927 "The number of milliseconds between two triggers 928 generated by this periodic timing object. 930 The execution system must not generate triggers 931 for periodic timing objects that have a interval 932 value of 0. A timing object with an interval of 933 0 milliseconds will therefore never trigger."; 934 } 935 uses timing-start-end-grouping; 936 } 937 } 939 case calendar { 940 container calendar { 941 description 942 "A calendar timing object trigger based on the 943 current calendar date and time."; 945 leaf-list month { 946 type union { 947 type month; 948 type wildcard; 949 } 950 description 951 "A month at which this calendar timing will 952 trigger. The wildcard means all months."; 953 } 955 leaf-list weekday { 956 type union { 957 type weekday; 958 type wildcard; 959 } 960 description 961 "A weekday at which this calendar timing will 962 trigger. The wildcard means all weekdays."; 963 } 965 leaf-list day-of-month { 966 type union { 967 type int8 { range "-31..-1 | 1..31"; } 968 type wildcard; 969 } 970 description 971 "A day in the month at which this calendar 972 timing will trigger. Negative numbers indicate 973 days counted backwards from the end of the 974 months. The wildcard means all days of a month."; 975 } 977 leaf-list hour { 978 type union { 979 type int8 { range "0..23"; } 980 type wildcard; 981 } 982 description 983 "An hour at which this calendar timing will 984 trigger. The wildcard means all hours of a day."; 985 } 987 leaf-list minute { 988 type union { 989 type int8 { range "0..59"; } 990 type wildcard; 991 } 992 description 993 "A minute at which this calendar timing will 994 trigger. The wildcard means all minutes of 995 an hour."; 996 } 998 leaf-list second { 999 type union { 1000 type int8 { range "0..59"; } 1001 type wildcard; 1002 } 1003 description 1004 "A second at which this calendar timing will 1005 trigger. The wildcard means all seconds of 1006 a minute."; 1007 } 1009 leaf timezone-offset { 1010 type timezone-offset; 1011 description 1012 "The timezone in which this calendar timing 1013 object will be evaluated."; 1014 } 1015 uses timing-start-end-grouping; 1016 } 1017 } 1019 case one-off { 1020 leaf one-off-time { 1021 type yang:date-and-time; 1022 mandatory true; 1023 description 1024 "This one-off timing object triggers once at the 1025 configured one-off-time."; 1026 } 1027 } 1029 case immediate { 1030 leaf immediate { 1031 type empty; 1032 mandatory true; 1033 description 1034 "This immediate timing object triggers immediately 1035 when it is configured."; 1036 } 1037 } 1039 case startup { 1040 leaf startup { 1041 type empty; 1042 mandatory true; 1043 description 1044 "This startup timing object triggers whenever the 1045 LMAP agent (re)starts."; 1046 } 1047 } 1048 } 1050 leaf random-spread { 1051 type int32; 1052 units milliseconds; 1053 description 1054 "This optional leaf adds a random spread to the 1055 computation of the trigger."; 1056 } 1057 } 1058 } 1059 } 1061 /* 1062 * The state subtree provides information about the capabilities 1063 * and the current status of the MA. 1064 */ 1066 container lmap-state { 1067 config false; 1068 description 1069 "A tree exporting state information about the LMAP agent."; 1071 container agent { 1072 description 1073 "Operations state of the measurement agent."; 1075 leaf agent-id { 1076 type yang:uuid; 1077 mandatory true; 1078 description 1079 "The agent-id identifies a measurement agent with 1080 a very low probability of collision. In certain 1081 deployments, the agent-id may be considered 1082 sensitive and hence this object is optional."; 1083 } 1085 leaf device-id { 1086 type inet:uri; 1087 mandatory true; 1088 description 1089 "The device-id identifies a property of the 1090 device running the measurement agent. In certain 1091 deployments, the device-id may be considered 1092 sensitive and hence this object is optional."; 1093 } 1094 leaf hardware { 1095 type string; 1096 mandatory true; 1097 description 1098 "A short description of the hardware the measurement 1099 agent is running on. This should include the version 1100 number of the hardware"; 1101 } 1102 leaf firmware { 1103 type string; 1104 mandatory true; 1105 description 1106 "A short description of the firmware the measurement 1107 agent is running on. This should include the version 1108 number of the firmware."; 1109 } 1110 leaf version { 1111 type string; 1112 mandatory true; 1113 description 1114 "A short description of the software implementing the 1115 measurement agent. This should include the version 1116 number of the measurement agent software."; 1117 } 1118 leaf last-started { 1119 type yang:date-and-time; 1120 mandatory true; 1121 description 1122 "The date and time the measurement agent last started."; 1123 } 1124 } 1126 container tasks { 1127 description 1128 "Available LMAP tasks, including information about their 1129 last execution and their last failed execution."; 1131 list task { 1132 key name; 1133 description 1134 "The list of tasks available on the LMAP agent."; 1136 leaf name { 1137 type string; 1138 description 1139 "The unique name of a task."; 1140 } 1142 choice task-identification { 1143 mandatory true; 1144 description 1145 "Information that identifies the task."; 1147 leaf registry { 1148 type inet:uri; 1149 description 1150 "The registry entry identifying the configured task."; 1151 } 1153 leaf program { 1154 type string; 1155 description 1156 "The (local) program to invoke in order to execute 1157 the task."; 1158 } 1159 } 1161 leaf last-completion { 1162 type yang:date-and-time; 1163 description 1164 "The date and time of the last completion of this task."; 1165 } 1167 leaf last-status { 1168 type status-code; 1169 description 1170 "The status code returned by the last execution of 1171 this task."; 1172 } 1174 leaf last-message { 1175 type string; 1176 description 1177 "The status message produced by the last execution 1178 of this task."; 1179 } 1181 leaf last-failed-completion { 1182 type yang:date-and-time; 1183 description 1184 "The date and time of the last failed invocation 1185 of this task."; 1186 } 1188 leaf last-failed-status { 1189 type status-code; 1190 description 1191 "The status code returned by the last failed execution 1192 of this task. "; 1193 } 1195 leaf last-failed-message { 1196 type string; 1197 description 1198 "The status message produced by the last failed 1199 execution of this task."; 1200 } 1201 } 1202 } 1203 } 1204 } 1205 1207 file "ietf-lmap-report@2015-04-10.yang" 1208 module ietf-lmap-report { 1210 namespace "urn:ietf:params:xml:ns:yang:ietf-lmap-report"; 1211 prefix "lmapr"; 1213 import ietf-yang-types { 1214 prefix yang; 1215 } 1216 import ietf-lmap-control { 1217 prefix lmapc; 1218 } 1220 organization 1221 "IETF Large-Scale Measurement Platforms Working Group"; 1223 contact 1224 "WG Web: 1225 WG List: 1227 Editor: Juergen Schoenwaelder 1228 1230 Editor: Vaibhav Bajpai 1231 "; 1233 description 1234 "This module defines a data model for reporting results from 1235 measurement agents that are part of a Large-Scale Measurement 1236 Platform (LMAP)."; 1238 revision "2015-04-10" { 1239 description 1240 "Initial version"; 1241 reference 1242 "RFC XXX: A YANG Data Model for LMAP Measurement Agents"; 1243 } 1245 notification report { 1246 description 1247 "The result record produced by a certain task."; 1249 leaf date { 1250 type yang:date-and-time; 1251 mandatory true; 1252 description 1253 "The date and time when this report was sent."; 1254 // XXX It is unclear why this is useful. The receiver can 1255 // XXX easily timestamp when data was received. 1256 } 1258 leaf agent-id { 1259 type yang:uuid; 1260 description 1261 "The agent-id of the agent from which this 1262 report originates."; 1263 } 1265 leaf group-id { 1266 type string; 1267 description 1268 "The group-id of the agent from which this 1269 report originates."; 1270 } 1272 uses lmapc:task-grouping; 1273 // XXX We would prefer to just send a configuration version 1274 // XXX number such that the configuration can be identified 1275 // XXX that was active XXX when the report was generated. It 1276 // XXX would be nice to have a generic configuration version 1277 // XXX number that we could reuse. If this works out, we can 1278 // XXX inline the grouping as well. 1280 // XXX Note that task-grouping contains stuff that is not 1281 // XXX relevant here, perhaps using a grouping is not helpful 1282 // XXX here. It is also missing stuff, such as the options 1283 // XXX in the schedule entry. 1285 container header { 1286 description 1287 "The header of the result records."; 1289 leaf-list column { 1290 type string; 1291 description 1292 "A header of a column in the result rows."; 1293 } 1294 } 1296 list row { 1297 description 1298 "The rows of the result record."; 1300 leaf start { 1301 type yang:date-and-time; 1302 mandatory true; 1303 description 1304 "The date and time when the measurement producing 1305 this result row started."; 1306 } 1308 leaf end { 1309 type yang:date-and-time; 1310 description 1311 "The date and time when the measurement producing 1312 this result row stopped."; 1313 } 1315 leaf-list conflict { 1316 type string; 1317 description 1318 "The name of a task overlapping with the execution 1319 of the task that has produced this result record."; 1320 } 1322 leaf-list value { 1323 type string; 1324 description 1325 "The value of a cell in the result."; 1326 // XXX We could make this a union / choice in order to a 1327 // XXX more compact encoding of numbers in certain encodings 1328 // XXX (e.g. JSON) 1329 } 1330 } 1331 } 1332 } 1333 1335 5. Security Considerations 1337 TBD 1339 6. IANA Considerations 1341 This document registers a URI in the "IETF XML Registry" [RFC3688]. 1342 Following the format in RFC 3688, the following registrations have 1343 been made. 1345 URI: urn:ietf:params:xml:ns:yang:ietf-lmap-control 1346 Registrant Contact: The IESG. 1347 XML: N/A; the requested URI is an XML namespace. 1349 URI: urn:ietf:params:xml:ns:yang:ietf-lmap-report 1350 Registrant Contact: The IESG. 1351 XML: N/A; the requested URI is an XML namespace. 1353 This document registers a YANG module in the "YANG Module Names" 1354 registry [RFC6020]. 1356 name: ietf-lmap-control 1357 namespace: urn:ietf:params:xml:ns:yang:ietf-lmap-control 1358 prefix: lmapc 1359 reference: RFC XXXX 1361 name: ietf-lmap-report 1362 namespace: urn:ietf:params:xml:ns:yang:ietf-lmap-report 1363 prefix: lmapr 1364 reference: RFC XXXX 1366 7. Acknowledgements 1368 Juergen Schoenwaelder and Vaibhav Bajpai work in part on the Leone 1369 research project, which receives funding from the European Union 1370 Seventh Framework Programme [FP7/2007-2013] under grant agreement 1371 number 317647. 1373 8. References 1375 8.1. Normative References 1377 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1378 Requirement Levels", BCP 14, RFC 2119, March 1997. 1380 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1381 Network Configuration Protocol (NETCONF)", RFC 6020, 1382 October 2010. 1384 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 1385 July 2013. 1387 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1388 Management", RFC 7223, May 2014. 1390 8.2. Informative References 1392 [I-D.ietf-lmap-framework] 1393 Eardley, P., Morton, A., Bagnulo, M., Burbridge, T., 1394 Aitken, P., and A. Akhter, "A framework for Large-Scale 1395 Measurement of Broadband Performance (LMAP)", draft-ietf- 1396 lmap-framework-12 (work in progress), March 2015. 1398 [I-D.ietf-lmap-information-model] 1399 Burbridge, T., Eardley, P., Bagnulo, M., and J. 1400 Schoenwaelder, "Information Model for Large-Scale 1401 Measurement Platforms (LMAP)", draft-ietf-lmap- 1402 information-model-05 (work in progress), April 2015. 1404 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1405 January 2004. 1407 Appendix A. Example Configuration (XML) 1409 1410 1412 1413 550e8400-e29b-41d4-a716-446655440000 1414 urn:dev:mac:0024befffe804ff1 1415 wireless measurement at the north-pole 1416 true 1417 1419 1420 1421 weekdays-hourly 1422 1423 udp-latency-weekdays-hourly 1424 udp-latency-measurement 1425 1426 q-all 1427 daily 1428 report-daily 1429 1430 1431 hourly 1432 1434 1435 hourly 1436 1437 icmp-latency-hourly 1438 icmp-latency-measurement 1439 1440 q-all 1441 daily 1442 report-daily 1443 1444 1445 hourly 1446 1448 1449 daily 1450 1451 report-daily 1452 lmap-reporting-task 1453 1457 1458 daily 1459 1461 1462 immediate 1463 1464 icmp-latency-immediate 1465 icmp-latency-measurement 1466 1467 q-all 1468 immediate 1469 report-immediate 1470 1471 1472 1473 report-immediate 1474 lmap-reporting-task 1475 1479 1480 immediate 1481 1482 1483 1485 1486 true 1487 2014-09-02T14:06:11+02:00 1488 iperf-server 1489 hourly 1490 weekdays-hourly 1491 1493 1494 1495 default-collector-channel 1496 1497 1498 1499 1500 udp-latency-measurement 1501 urn:.... 1502 1503 1504 icmp-latency-measurement 1505 urn:.... 1506 1507 1508 iperf-server 1509 iperf 1510 1514 false 1515 1516 1517 lmap-reporting-task 1518 lmap-reportd 1519 1520 1522 1523 1524 hourly 1525 1526 3600000 1527 2014-09-01T17:44:00+02:00 1528 2014-09-30T00:00:00+02:00 1529 1530 1531 1532 daily 1533 1534 04 1535 1536 1537 1538 tuesday-thursday-sunday 1539 1540 tuesday 1541 thursday 1542 sunday 1543 18 1544 04 1545 42 1546 2014-09-30T00:00:00+02:00 1547 1548 1549 1550 once-every-six-hours 1551 1552 0 1553 6 1554 12 1555 18 1556 0 1557 0 1558 2014-09-30T00:00:00+02:00 1559 1560 21600000 1561 1562 1563 immediate 1564 1565 1566 1567 startup 1568 1569 12345 1570 1571 1573 1575 1577 1578 550e8400-e29b-41d4-a716-446655440000 1579 urn:dev:mac:0024befffe804ff1 1580 ACME home router 1581 OpenWrt version 10.03.1 1582 Measurement Agent Daemon (MAD) 4.2 1583 2015-04-10T17:24:42+02:00 1584 1586 1587 1588 udp-latency-measurement 1589 urn:.... 1590 1592 1593 icmp-latency-measurement 1594 urn:.... 1595 1597 1598 iperf 1599 iperf 1600 1602 1603 lmap-reporting-task 1604 lmap-reportd 1605 2015-01-23T12:00:00+01:00 1606 0 1607 OK 1608 2015-01-23T03:00:00+01:00 1609 42 1610 connection timed out 1611 1612 1614 1615 1617 Appendix B. Example Configuration (JSON) 1619 { 1620 "ietf-lmap-control:lmap": { 1621 "agent": { 1622 "agent-id": "550e8400-e29b-41d4-a716-446655440000", 1623 "device-id": "urn:dev:mac:0024befffe804ff1", 1624 "group-id": "wireless measurement at the north-pole", 1625 "report-agent-id": true 1626 }, 1627 "schedules": { 1628 "schedule": [ 1629 { 1630 "name": "weekdays-hourly", 1631 "action": [ 1632 { 1633 "name": "udp-latency-weekdays-hourly", 1634 "task": "udp-latency-measurement", 1635 "destination": [ 1636 { 1637 "name": "q-all", 1638 "schedule": "daily", 1639 "action": "report-daily" 1641 } 1642 ] 1643 } 1644 ], 1645 "timing": "hourly" 1646 }, 1647 { 1648 "name": "hourly", 1649 "action": [ 1650 { 1651 "name": "icmp-latency-hourly", 1652 "task": "icmp-latency-measurement", 1653 "destination": [ 1654 { 1655 "name": "q-all", 1656 "schedule": "daily", 1657 "action": "report-daily" 1658 } 1659 ] 1660 } 1661 ], 1662 "timing": "hourly" 1663 }, 1664 { 1665 "name": "daily", 1666 "action": [ 1667 { 1668 "name": "report-daily", 1669 "task": "lmap-reporting-task", 1670 "option": [ 1671 { 1672 "name": "channel", 1673 "value": "default-collector-channel" 1674 } 1675 ] 1676 } 1677 ], 1678 "timing": "daily" 1679 }, 1680 { 1681 "name": "immediate", 1682 "action": [ 1683 { 1684 "name": "icmp-latency-immediate", 1685 "task": "icmp-latency-measurement", 1686 "destination": [ 1687 { 1688 "name": "q-all", 1689 "schedule": "immediate", 1690 "action": "report-immediate" 1691 } 1692 ] 1693 }, 1694 { 1695 "name": "report-immediate", 1696 "task": "lmap-reporting-task", 1697 "option": [ 1698 { 1699 "name": "channel", 1700 "value": "default-collector-channel" 1701 } 1702 ] 1703 } 1704 ], 1705 "timing": "immediate" 1706 } 1707 ] 1708 }, 1709 "suppression": { 1710 "enabled": true, 1711 "start": "2014-09-02T14:06:11+02:00", 1712 "task": [ 1713 "iperf-server" 1714 ], 1715 "schedule": [ 1716 "hourly", 1717 "weekdays-hourly" 1718 ] 1719 }, 1720 "channels": { 1721 "channel": [ 1722 { 1723 "name": "default-collector-channel" 1724 } 1725 ] 1726 }, 1727 "tasks": { 1728 "task": [ 1729 { 1730 "name": "udp-latency-measurement", 1731 "registry": "urn:...." 1732 }, 1733 { 1734 "name": "icmp-latency-measurement", 1735 "registry": "urn:...." 1736 }, 1737 { 1738 "name": "iperf-server", 1739 "program": "iperf", 1740 "option": [ 1741 { 1742 "name": "role", 1743 "value": "server" 1744 } 1745 ], 1746 "suppress-by-default": false 1747 }, 1748 { 1749 "name": "lmap-reporting-task", 1750 "program": "lmap-reportd" 1751 } 1752 ] 1753 }, 1754 "timings": { 1755 "timing": [ 1756 { 1757 "name": "hourly", 1758 "periodic": { 1759 "interval": 3600000, 1760 "start": "2014-09-01T17:44:00+02:00", 1761 "end": "2014-09-30T00:00:00+02:00" 1762 } 1763 }, 1764 { 1765 "name": "daily", 1766 "calendar": { 1767 "hour": [ 1768 04 1769 ] 1770 } 1771 }, 1772 { 1773 "name": "tuesday-thursday-sunday", 1774 "calendar": { 1775 "weekday": [ 1776 "tuesday", 1777 "thursday", 1778 "sunday" 1779 ], 1780 "hour": [ 1781 18 1782 ], 1783 "minute": [ 1784 04 1786 ], 1787 "second": [ 1788 42 1789 ], 1790 "end": "2014-09-30T00:00:00+02:00" 1791 } 1792 }, 1793 { 1794 "name": "once-every-six-hours", 1795 "calendar": { 1796 "hour": [ 1797 0, 1798 6, 1799 12, 1800 18 1801 ], 1802 "minute": [ 1803 0 1804 ], 1805 "second": [ 1806 0 1807 ], 1808 "end": "2014-09-30T00:00:00+02:00" 1809 }, 1810 "random-spread": 21600000 1811 }, 1812 { 1813 "name": "immediate", 1814 "immediate": [null] 1815 }, 1816 { 1817 "name": "startup", 1818 "startup": [null], 1819 "random-spread": 12345 1820 } 1821 ] 1822 } 1823 }, 1824 "ietf-lmap-control:lmap-state": { 1825 "agent": { 1826 "agent-id": "550e8400-e29b-41d4-a716-446655440000", 1827 "device-id": "urn:dev:mac:0024befffe804ff1", 1828 "hardware": "ACME home router", 1829 "firmware": "OpenWrt version 10.03.1", 1830 "version": "Measurement Agent Daemon (MAD) 4.2", 1831 "last-started": "2015-04-10T17:24:42+02:00" 1832 }, 1833 "tasks": { 1834 "task": [ 1835 { 1836 "name": "udp-latency-measurement", 1837 "registry": "urn:...." 1838 }, 1839 { 1840 "name": "icmp-latency-measurement", 1841 "registry": "urn:...." 1842 }, 1843 { 1844 "name": "iperf", 1845 "program": "iperf" 1846 }, 1847 { 1848 "name": "lmap-reporting-task", 1849 "program": "lmap-reportd", 1850 "last-completion": "2015-01-23T12:00:00+01:00", 1851 "last-status": 0, 1852 "last-message": "OK", 1853 "last-failed-completion": "2015-01-23T03:00:00+01:00", 1854 "last-failed-status": 42, 1855 "last-failed-message": "connection timed out" 1856 } 1857 ] 1858 } 1859 } 1860 } 1862 Authors' Addresses 1864 Juergen Schoenwaelder 1865 Jacobs University Bremen 1867 Email: j.schoenwaelder@jacobs-university.de 1869 Vaibhav Bajpai 1870 Jacobs University Bremen 1872 Email: v.bajpai@jacobs-university.de