idnits 2.17.1 draft-ietf-lmap-yang-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 10 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 129 has weird spacing: '...on-mode enu...' == Line 156 has weird spacing: '...nterval uin...' == Line 188 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 (July 3, 2015) is 3210 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-06 == Outdated reference: A later version (-09) exists of draft-ietf-netconf-server-model-06 Summary: 2 errors (**), 0 flaws (~~), 8 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: January 4, 2016 July 3, 2015 7 A YANG Data Model for LMAP Measurement Agents 8 draft-ietf-lmap-yang-01.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 January 4, 2016. 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 . . . . . . . . . . . . . . . . . . . 28 57 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 58 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 29 59 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 29 60 8.1. Normative References . . . . . . . . . . . . . . . . . . 29 61 8.2. Informative References . . . . . . . . . . . . . . . . . 29 62 Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . 30 63 Appendix B. Non-editorial Changes since -06 . . . . . . . . . . 30 64 Appendix C. Example Configuration (XML) . . . . . . . . . . . . 30 65 Appendix D. Example Configuration (JSON) . . . . . . . . . . . . 34 66 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 38 68 1. Introduction 70 This document defines a data model for Large-Scale Measurement 71 Platforms (LMAP) [I-D.ietf-lmap-framework]. The data model is 72 defined using the YANG [RFC6020] data modeling language. It aims to 73 be consistent with the LMAP Information Model 74 [I-D.ietf-lmap-information-model]. 76 1.1. Terminology 78 This document uses the LMAP terminology defined in 79 [I-D.ietf-lmap-framework]. 81 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 82 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 83 document are to be interpreted as described in [RFC2119]. 85 1.2. Tree Diagrams 87 A simplified graphical representation of the data model is used in 88 this document. The meaning of the symbols in these diagrams is as 89 follows: 91 o Brackets "[" and "]" enclose list keys. 93 o Abbreviations before data node names: "rw" means configuration 94 (read-write), and "ro" means state data (read-only). 96 o Symbols after data node names: "?" means an optional node, "!" 97 means a presence container, and "*" denotes a list and leaf-list. 99 o Parentheses enclose choice and case nodes, and case nodes are also 100 marked with a colon (":"). 102 o Ellipsis ("...") stands for contents of subtrees that are not 103 shown. 105 2. Data Model Overview 107 The tree diagram below shows the structure of the configuration 108 model. 110 module: ietf-lmap-control 111 +--rw lmap 112 +--rw agent 113 | +--rw agent-id? yang:uuid 114 | +--rw device-id? inet:uri 115 | +--rw group-id? string 116 | +--rw report-agent-id? boolean 117 | +--rw controller-timeout? uint32 118 +--rw schedules 119 | +--rw schedule* [name] 120 | +--rw name string 121 | +--rw event -> /lmap/events/event/name 122 | +--rw action* [name] 123 | | +--rw name string 124 | | +--rw task -> /lmap/tasks/task/name 125 | | +--rw option* [name] 126 | | | +--rw name string 127 | | | +--rw value? string 128 | | +--rw destination* -> /lmap/schedules/schedule/name 129 | +--rw execution-mode enumeration 130 +--rw suppression 131 | +--rw enabled? boolean 132 | +--rw stop-running? boolean 133 | +--rw start? yang:date-and-time 134 | +--rw end? yang:date-and-time 135 | +--rw task* -> /lmap/tasks/task/name 136 | +--rw schedule* -> /lmap/schedules/schedule/name 137 +--rw tasks 138 | +--rw task* [name] 139 | +--rw name string 140 | +--rw (task-identification) 141 | | +--:(registry) 142 | | | +--rw registry* inet:uri 143 | | +--:(program) 144 | | +--rw program? string 145 | +--rw option* [name] 146 | | +--rw name string 147 | | +--rw value? string 148 | +--rw tag* string 149 | +--rw suppress-by-default? boolean 150 +--rw events 151 +--rw event* [name] 152 +--rw name string 153 +--rw (event-type)? 154 | +--:(periodic) 155 | | +--rw periodic 156 | | +--rw interval uint32 157 | | +--rw start? yang:date-and-time 158 | | +--rw end? yang:date-and-time 159 | +--:(calendar) 160 | | +--rw calendar 161 | | +--rw month* union 162 | | +--rw weekday* union 163 | | +--rw day-of-month* union 164 | | +--rw hour* union 165 | | +--rw minute* union 166 | | +--rw second* union 167 | | +--rw timezone-offset? timezone-offset 168 | | +--rw start? yang:date-and-time 169 | | +--rw end? yang:date-and-time 170 | +--:(one-off) 171 | | +--rw one-off-time yang:date-and-time 172 | +--:(immediate) 173 | | +--rw immediate empty 174 | +--:(startup) 175 | +--rw startup empty 176 +--rw random-spread? int32 178 The tree diagram below shows the structure of the state model. 180 module: ietf-lmap-control 181 +--ro lmap-state 182 +--ro agent 183 | +--ro agent-id yang:uuid 184 | +--ro device-id inet:uri 185 | +--ro hardware string 186 | +--ro firmware string 187 | +--ro version string 188 | +--ro last-started yang:date-and-time 189 +--ro tasks 190 +--ro task* [name] 191 +--ro name string 192 +--ro (task-identification) 193 | +--:(registry) 194 | | +--ro registry* inet:uri 195 | +--:(program) 196 | +--ro program? string 197 +--ro last-completion? yang:date-and-time 198 +--ro last-status? status-code 199 +--ro last-message? string 200 +--ro last-failed-completion? yang:date-and-time 201 +--ro last-failed-status? status-code 202 +--ro last-failed-message? string 204 The tree diagram below shows the structure of the notification 205 (reporting) model. 207 module: ietf-lmap-report 208 notifications: 209 +---n report 210 +--ro date yang:date-and-time 211 +--ro agent-id? yang:uuid 212 +--ro group-id? string 213 +--ro task* [name] 214 | +--ro name string 215 | +--ro (task-identification) 216 | | +--:(registry) 217 | | | +--ro registry? inet:uri 218 | | +--:(program) 219 | | +--ro program? string 220 | +--ro option* [name] 221 | | +--ro name string 222 | | +--ro value? string 223 | +--ro tag* string 224 | +--ro suppress-by-default? boolean 225 +--ro header 226 | +--ro column* string 227 +--ro row* 228 +--ro start yang:date-and-time 229 +--ro end? yang:date-and-time 230 +--ro conflict* string 231 +--ro value* string 233 3. Relationship to the Information Model 235 The LMAP information model [I-D.ietf-lmap-information-model] is 236 devided into six sections. They are mapped into the YANG data model 237 as explained below: 239 o Pre-Configuration Information: This is not modeled explicitly 240 since it is a subset of the configuration information. 242 o Configuration Information: This is modeled in the /lmap/agent 243 subtree and the /lmap/schedules and /lmap/tasks subtrees described 244 below. Some items have been left out because they are expected to 245 be dealt with by the underlying protocol. 247 o Instruction Information: This is modeled in the /lmap/suppression 248 subtree and the /lmap/schedules and /lmap/tasks subtrees described 249 below. 251 o Logging Information: Some of the logging information, in 252 particular 'success/failure/warning messages in response to 253 information updates from the Controller', will be handled by the 254 protocol used to manipulate the lmap specific configuration. 255 [[CREF1: It needs to be discussed whether we can rely on informal 256 syslog messages that can be accessed via protocols such RFC 5277 257 or whether we want to define specific notifications in the YANG 258 data model. --JS]] 260 o Capability and Status Information: Some of the status information 261 is modeled in the /lmap-state/agent subtree. Information about 262 network interfaces can be obtained from the interfaces YANG data 263 model [RFC7223]. The list of supported tasks is modeled in the 264 /lmap-state/tasks subtree including information about the last 265 execution and the last failed execution. 267 o Reporting Information: This is modeled by the report notification. 269 These six sections are build on the following common information 270 objects: 272 o Schedules: This is modeled in the /lmap/schedules subtree. 274 o Channels: Channels are not modeled since the NETCONF and RESTCONF 275 server configuration data model [I-D.ietf-netconf-server-model] 276 already provides a mechanism to configure NETCONF and RESTCONF 277 server channels. 279 o Task Configurations: This is modeled in the /lmap/tasks subtree. 281 o Event Information: This is modeled in the /lmap/events subtree. 283 4. YANG Modules 285 The modules import definitions from [RFC6991] and [RFC7223]. 287 file "ietf-lmap-control@2015-07-03.yang" 288 module ietf-lmap-control { 290 namespace "urn:ietf:params:xml:ns:yang:ietf-lmap-control"; 291 prefix "lmapc"; 293 import ietf-yang-types { 294 prefix yang; 295 } 296 import ietf-inet-types { 297 prefix inet; 298 } 300 organization 301 "IETF Large-Scale Measurement Platforms Working Group"; 303 contact 304 "WG Web: 305 WG List: 307 Editor: Juergen Schoenwaelder 308 310 Editor: Vaibhav Bajpai 311 "; 313 description 314 "This module defines a data model for controlling measurement 315 agents that are part of a Large-Scale Measurement Platform 316 (LMAP)."; 318 revision "2015-07-03" { 319 description 320 "Initial version"; 321 reference 322 "RFC XXX: A YANG Data Model for LMAP Measurement Agents"; 323 } 325 /* 326 * Typedefs 327 */ 329 typedef weekday { 330 type enumeration { 331 enum sunday { 332 value 0; 333 description "Sunday of the week"; 334 } 335 enum monday { 336 value 1; 337 description "Monday of the week"; 338 } 339 enum tuesday { 340 value 2; 341 description "Tuesday of the week"; 342 } 343 enum wednesday { 344 value 3; 345 description "Wednesday of the week"; 346 } 347 enum thursday { 348 value 4; 349 description "Thursday of the week"; 350 } 351 enum friday { 352 value 5; 353 description "Friday of the week"; 354 } 355 enum saturday { 356 value 6; 357 description "Saturday of the week"; 358 } 359 } 360 description 361 "A type modeling the weekdays in the Greco-Roman 362 tradition."; 363 } 365 typedef month { 366 type enumeration { 367 enum january { 368 value 1; 369 description "January of the Julian and Gregorian calendar"; 370 } 371 enum february { 372 value 2; 373 description "February of the Julian and Gregorian calendar"; 374 } 375 enum march { 376 value 3; 377 description "March of the Julian and Gregorian calendar"; 378 } 379 enum april { 380 value 4; 381 description "April of the Julian and Gregorian calendar"; 382 } 383 enum may { 384 value 5; 385 description "May of the Julian and Gregorian calendar"; 386 } 387 enum june { 388 value 6; 389 description "June of the Julian and Gregorian calendar"; 390 } 391 enum july { 392 value 7; 393 description "July of the Julian and Gregorian calendar"; 394 } 395 enum august { 396 value 8; 397 description "August of the Julian and Gregorian calendar"; 398 } 399 enum september { 400 value 9; 401 description "September of the Julian and Gregorian calendar"; 402 } 403 enum october { 404 value 10; 405 description "October of the Julian and Gregorian calendar"; 406 } 407 enum november { 408 value 11; 409 description "November of the Julian and Gregorian calendar"; 410 } 411 enum december { 412 value 12; 413 description "December of the Julian and Gregorian calendar"; 414 } 415 } 416 description 417 "A type modeling the month in the Julian and Gregorian 418 tradition."; 419 } 421 typedef wildcard { 422 type string { pattern '\*'; } 423 description 424 "A wildcard for calendar scheduling entries."; 425 } 427 typedef status-code { 428 type int32; 429 description 430 "A status code returned by the execution of a task. Note that 431 the actual range is implementation dependent but it should 432 be portable to use values in the range 0..127 for regular 433 exit codes. By convention, 0 indicates successful termination. 434 Negative values may be used to indicate abnormal termination 435 due to a signal; the absolute value may identify the signal 436 number in this case."; 437 } 439 typedef timezone-offset { 440 type string { 441 pattern 'Z|[\+\-]\d{2}:\d{2}'; 442 } 443 description 444 "A timezone-offset as it is use in the yang:date-and-time 445 type. The value Z is equivalent to +00:00. The value -00:00 446 indicates and unknown time-offset."; 447 } 449 /* 450 * Groupings 451 */ 453 grouping timing-start-end-grouping { 454 description 455 "A grouping that provides start and end times for 456 timing objects."; 457 leaf start { 458 type yang:date-and-time; 459 description 460 "The date and time when the timing object 461 starts to create triggers."; 462 } 463 leaf end { 464 type yang:date-and-time; 465 description 466 "The date and time when the timing object 467 stops to create triggers. 469 It is generally a good idea to always configure 470 an end time and to refresh the configuration 471 of timing object as needed to ensure that agents 472 that loose connectivity to their controller 473 do not continue their tasks forever."; 474 } 475 } 477 grouping task-options-grouping { 478 description 479 "A list of options of a task. Each option is a name/value 480 pair (where the value may be absent)."; 482 list option { 483 key "name"; 484 ordered-by user; 486 description 487 "A list of options passed to the task. It is a list of 488 key / value pairs and may be used to model options. 489 Options may be used to identify the role of a task 490 or to pass a channel name to a task."; 492 // XXX This is kind of broken since making the option name 493 // XXX a key means that a certain option may only appear once. 494 // XXX This is not workable since some tests require a list of 495 // XXX targets. Turning this into a leaf-list of args also 496 // XXX does not work since YANG requires leaf-list values to 497 // XXX be unique. Oops. 499 leaf name { 500 type string; 501 description 502 "The name of the option."; 503 } 505 leaf value { 506 type string; 507 description 508 "The value of the option."; 509 } 510 } 511 } 513 grouping task-grouping { 514 description 515 "A grouping that defines the configuration of a task."; 517 list task { 518 key name; 519 description 520 "The list of tasks configured on the LMAP agent."; 522 leaf name { 523 type string; 524 description 525 "The unique name of a task."; 526 } 528 choice task-identification { 529 mandatory true; 530 description 531 "Information that identifies the task."; 533 leaf-list registry { 534 type inet:uri; 535 description 536 "A registry entry identifying the metrics a measurement 537 task supports."; 538 } 540 leaf program { 541 type string; 542 description 543 "The (local) program to invoke in order to execute 544 the task."; 545 } 546 } 548 uses task-options-grouping { 549 description 550 "The list of task specific options."; 551 } 553 leaf-list tag { 554 type string; 555 description 556 "A tag contains additional information that is passed 557 with the result record to the collector. A tag can be 558 used to carry the Measurement Cycle ID."; 559 } 561 leaf suppress-by-default { 562 type boolean; 563 default true; 564 description 565 "Indicates whether the task will be suppressed by 566 a default supression."; 567 } 568 } 569 } 571 /* 572 * Configuration data nodes 573 */ 575 container lmap { 576 description 577 "Configuration of the LMAP agent."; 579 /* 580 * Common Information Objects: Configuration 581 */ 583 container agent { 584 description 585 "Configuration of parameters affecting the whole 586 measurement agent."; 588 leaf agent-id { 589 type yang:uuid; 590 description 591 "The agent-id identifies a measurement agent with 592 a very low probability of collision. In certain 593 deployments, the agent-id may be considered 594 sensitive and hence this object is optional."; 595 } 597 leaf device-id { 598 type inet:uri; 599 description 600 "The device-id identifies a property of the 601 device running the measurement agent. In certain 602 deployments, the device-id may be considered 603 sensitive and hence this object is optional."; 604 } 606 leaf group-id { 607 type string; 608 description 609 "The group-id identifies a group of measurement 610 agents. In certain deployments, the group-id 611 may be considered less sensitive than the 612 agent-id."; 613 } 615 leaf report-agent-id { 616 type boolean; 617 default false; 618 // XXX: write a must expression that requires 619 // group-id to be configured when this is true? 620 description 621 "The 'report-agent-id' controls whether the 622 'agent-id' is reported to collectors if the 623 'group-id' is configured. If the 'group-id' 624 is not configured, the agent-id is always 625 reported."; 626 } 628 leaf controller-timeout { 629 type uint32; 630 units "seconds"; 631 description 632 "A timer is started after each successful contact 633 with a controller. When the timer reaches the 634 controller-timeout, all schedules will be 635 disabled, i.e., no new actions will be executed 636 (and hence no new tasks started). The disabled 637 schedules will be reenabled automatically once 638 contact with a controller has been established 639 successfully again. Note that this will not affect 640 the execution of actions that are essential to 641 establish contact with the controller or that 642 perform critical housekeeping functions."; 643 } 644 } 646 /* 647 * Common Information Objects: Schedules 648 */ 650 container schedules { 651 description 652 "Configuration of LMAP schedules. Schedules control with 653 tasks are executed by the LMAP implementation."; 655 list schedule { 656 key name; 657 description 658 "Configuration of a particular schedule."; 660 leaf name { 661 type string; 662 description 663 "The locally-unique, administratively assigned name for 664 this scheduled task."; 665 } 667 leaf event { 668 type leafref { 669 path "/lmap/events/event/name"; 670 } 671 mandatory true; 672 description 673 "The event source controlling the start of the scheduled 674 tasks."; 675 } 677 list action { 678 key name; 679 description 680 "An action describes a task that is invoked by the 681 schedule. Multiple actions are invoked sequentially."; 683 leaf name { 684 type string; 685 description 686 "The unique identifier for this action."; 687 } 689 leaf task { 690 type leafref { 691 path "/lmap/tasks/task/name"; 692 } 693 mandatory true; 694 description 695 "The tasks invoked by this action."; 696 } 698 uses task-options-grouping { 699 description 700 "The list of action specific options that are 701 appended to the list of task specific options."; 702 } 704 leaf-list destination { 705 type leafref { 706 path "/lmap/schedules/schedule/name"; 707 } 708 description 709 "A schedule of receiving the output produced by 710 this action. A queue is internally used to pass 711 results to another schedule. The behaviour of 712 an action passing data to its own schedule is 713 implementation specific."; 714 } 715 } 717 leaf execution-mode { 718 type enumeration { 719 enum sequential { 720 value 1; 721 description 722 "The actions of the schedule are executed 723 sequentially."; 724 } 725 enum parallel { 726 value 2; 727 description 728 "The actions of the schedule are executed 729 concurrently"; 730 } 731 enum pipelined { 732 value 3; 733 description 734 "The actions of the schedule are executed in a 735 pipelined mode. Output created by an action is 736 passed as input to the subsequent action."; 737 } 738 } 739 mandatory true; 740 description 741 "The execution mode of this schedule determins in 742 which order the actions of the schedule are executed."; 743 } 744 } 745 } 747 /* 748 * Suppression 749 */ 751 container suppression { 752 description 753 "Suppression information to prevent schedules to start 754 certain tasks."; 756 leaf enabled { 757 type boolean; 758 default false; 759 description 760 "Setting 'enabled' to true will suppress all tasks for 761 which suppress-by-default is true."; 762 } 764 leaf stop-running { 765 type boolean; 766 default false; 767 description 768 "Setting 'stop-running' to true will cause running 769 tasks to be terminated if suppression is enabled 770 (the 'enabled' leaf is set to true). Otherwise, 771 running tasks will not be affected if suppression 772 is enabled."; 773 } 775 leaf start { 776 type yang:date-and-time; 777 description 778 "The date and time when supression starts to 779 become effective. If not present, supression 780 becomes effective immeditately when 'enabled' 781 is set to true."; 782 } 784 leaf end { 785 type yang:date-and-time; 786 description 787 "The date and time when supression stops to 788 be effective. If not present, supression 789 continues indefinite until 'enabled' is set 790 to false."; 791 } 793 leaf-list task { 794 type leafref { 795 path "/lmap/tasks/task/name"; 796 } 797 description 798 "A specific task to suppress. If no tasks are 799 listed, then all tasks will be suppressed."; 800 } 802 leaf-list schedule { 803 type leafref { 804 path "/lmap/schedules/schedule/name"; 805 } 806 description 807 "A specific schedule to suppress. If no schedules 808 are listed, then all schedules will be suppressed."; 809 } 811 } 813 /* 814 * Common Information Objects: Task Configurations 815 */ 817 container tasks { 818 description 819 "Configuration of LMAP tasks."; 821 uses task-grouping; 822 } 824 /* 825 * Common Information Objects: Event Information 826 */ 828 container events { 829 description 830 "Configuration of LMAP events. 832 Implementations may be forced to delay acting 833 upon the occurance of events in the face of local 834 constraints. An action triggered by an event 835 therefore should not rely on the accuracy 836 provided by the scheduler implementation."; 838 list event { 839 key name; 840 description 841 "The list of event sources configured on the 842 LMAP agent."; 844 leaf name { 845 type string; 846 description 847 "The unique name of an event source."; 848 } 850 choice event-type { 851 description 852 "Different types of events are handled by 853 different branches of this choice. Note that 854 this choice can be extended via augmentations."; 856 case periodic { 857 container periodic { 858 description 859 "A periodic timing object triggers periodically 860 according to a regular interval."; 862 leaf interval { 863 type uint32; 864 units "milliseconds"; 865 mandatory true; 866 description 867 "The number of milliseconds between two triggers 868 generated by this periodic timing object. 870 The execution system must not generate triggers 871 for periodic timing objects that have a interval 872 value of 0. A periodic timing object with an 873 interval of 0 milliseconds will therefore never 874 trigger."; 875 } 876 uses timing-start-end-grouping; 878 } 879 } 881 case calendar { 882 container calendar { 883 description 884 "A calendar timing object triggers based on the 885 current calendar date and time."; 887 leaf-list month { 888 type union { 889 type month; 890 type wildcard; 891 } 892 description 893 "A month at which this calendar timing will 894 trigger. The wildcard means all months."; 895 } 897 leaf-list weekday { 898 type union { 899 type weekday; 900 type wildcard; 901 } 902 description 903 "A weekday at which this calendar timing will 904 trigger. The wildcard means all weekdays."; 905 } 907 leaf-list day-of-month { 908 type union { 909 type int8 { range "-31..-1 | 1..31"; } 910 type wildcard; 911 } 912 description 913 "A day in the month at which this calendar 914 timing will trigger. Negative numbers indicate 915 days counted backwards from the end of the 916 months. The wildcard means all days of a month."; 917 } 919 leaf-list hour { 920 type union { 921 type int8 { range "0..23"; } 922 type wildcard; 923 } 924 description 925 "An hour at which this calendar timing will 926 trigger. The wildcard means all hours of a day."; 927 } 929 leaf-list minute { 930 type union { 931 type int8 { range "0..59"; } 932 type wildcard; 933 } 934 description 935 "A minute at which this calendar timing will 936 trigger. The wildcard means all minutes of 937 an hour."; 938 } 940 leaf-list second { 941 type union { 942 type int8 { range "0..59"; } 943 type wildcard; 944 } 945 description 946 "A second at which this calendar timing will 947 trigger. The wildcard means all seconds of 948 a minute."; 949 } 951 leaf timezone-offset { 952 type timezone-offset; 953 description 954 "The timezone in which this calendar timing 955 object will be evaluated."; 956 } 957 uses timing-start-end-grouping; 958 } 959 } 961 case one-off { 962 leaf one-off-time { 963 type yang:date-and-time; 964 mandatory true; 965 description 966 "This one-off timing object triggers once at the 967 configured one-off-time."; 968 } 969 } 971 case immediate { 972 leaf immediate { 973 type empty; 974 mandatory true; 975 description 976 "This immediate event object triggers immediately 977 when it is configured."; 978 } 979 } 981 case startup { 982 leaf startup { 983 type empty; 984 mandatory true; 985 description 986 "This startup event object triggers whenever the 987 LMAP agent (re)starts."; 988 } 989 } 990 } 992 leaf random-spread { 993 type int32; 994 units milliseconds; 995 description 996 "This optional leaf adds a random spread to the 997 computation of the trigger."; 998 } 999 } 1000 } 1001 } 1003 /* 1004 * The state subtree provides information about the capabilities 1005 * and the current status of the MA. 1006 */ 1008 container lmap-state { 1009 config false; 1010 description 1011 "A tree exporting state information about the LMAP agent."; 1013 container agent { 1014 description 1015 "Operations state of the measurement agent."; 1017 leaf agent-id { 1018 type yang:uuid; 1019 mandatory true; 1020 description 1021 "The agent-id identifies a measurement agent with 1022 a very low probability of collision. In certain 1023 deployments, the agent-id may be considered 1024 sensitive and hence this object is optional."; 1025 } 1027 leaf device-id { 1028 type inet:uri; 1029 mandatory true; 1030 description 1031 "The device-id identifies a property of the 1032 device running the measurement agent. In certain 1033 deployments, the device-id may be considered 1034 sensitive and hence this object is optional."; 1035 } 1036 leaf hardware { 1037 type string; 1038 mandatory true; 1039 description 1040 "A short description of the hardware the measurement 1041 agent is running on. This should include the version 1042 number of the hardware"; 1043 } 1044 leaf firmware { 1045 type string; 1046 mandatory true; 1047 description 1048 "A short description of the firmware the measurement 1049 agent is running on. This should include the version 1050 number of the firmware."; 1051 } 1052 leaf version { 1053 type string; 1054 mandatory true; 1055 description 1056 "A short description of the software implementing the 1057 measurement agent. This should include the version 1058 number of the measurement agent software."; 1059 } 1060 leaf last-started { 1061 type yang:date-and-time; 1062 mandatory true; 1063 description 1064 "The date and time the measurement agent last started."; 1065 } 1066 } 1068 container tasks { 1069 description 1070 "Available LMAP tasks, including information about their 1071 last execution and their last failed execution."; 1073 list task { 1074 key name; 1075 description 1076 "The list of tasks available on the LMAP agent."; 1078 leaf name { 1079 type string; 1080 description 1081 "The unique name of a task."; 1082 } 1084 choice task-identification { 1085 mandatory true; 1086 description 1087 "Information that identifies the task."; 1089 leaf-list registry { 1090 type inet:uri; 1091 description 1092 "The registry entry identifying the configured task."; 1093 } 1095 leaf program { 1096 type string; 1097 description 1098 "The (local) program to invoke in order to execute 1099 the task."; 1100 } 1101 } 1103 leaf last-completion { 1104 type yang:date-and-time; 1105 description 1106 "The date and time of the last completion of this task."; 1107 } 1109 leaf last-status { 1110 type status-code; 1111 description 1112 "The status code returned by the last execution of 1113 this task."; 1114 } 1116 leaf last-message { 1117 type string; 1118 description 1119 "The status message produced by the last execution 1120 of this task."; 1121 } 1123 leaf last-failed-completion { 1124 type yang:date-and-time; 1125 description 1126 "The date and time of the last failed invocation 1127 of this task."; 1128 } 1130 leaf last-failed-status { 1131 type status-code; 1132 description 1133 "The status code returned by the last failed execution 1134 of this task. "; 1135 } 1137 leaf last-failed-message { 1138 type string; 1139 description 1140 "The status message produced by the last failed 1141 execution of this task."; 1142 } 1143 } 1144 } 1145 } 1146 } 1147 1149 file "ietf-lmap-report@2015-07-03.yang" 1150 module ietf-lmap-report { 1152 namespace "urn:ietf:params:xml:ns:yang:ietf-lmap-report"; 1153 prefix "lmapr"; 1155 import ietf-yang-types { 1156 prefix yang; 1157 } 1158 import ietf-lmap-control { 1159 prefix lmapc; 1160 } 1162 organization 1163 "IETF Large-Scale Measurement Platforms Working Group"; 1165 contact 1166 "WG Web: 1167 WG List: 1169 Editor: Juergen Schoenwaelder 1170 1172 Editor: Vaibhav Bajpai 1173 "; 1175 description 1176 "This module defines a data model for reporting results from 1177 measurement agents that are part of a Large-Scale Measurement 1178 Platform (LMAP)."; 1180 revision "2015-04-10" { 1181 description 1182 "Initial version"; 1183 reference 1184 "RFC XXX: A YANG Data Model for LMAP Measurement Agents"; 1185 } 1187 notification report { 1188 description 1189 "The result record produced by a certain task."; 1191 leaf date { 1192 type yang:date-and-time; 1193 mandatory true; 1194 description 1195 "The date and time when this report was sent."; 1196 // XXX It is unclear why this is useful. The receiver can 1197 // XXX easily timestamp when data was received. 1198 } 1200 leaf agent-id { 1201 type yang:uuid; 1202 description 1203 "The agent-id of the agent from which this 1204 report originates."; 1205 } 1207 leaf group-id { 1208 type string; 1209 description 1210 "The group-id of the agent from which this 1211 report originates."; 1212 } 1213 uses lmapc:task-grouping; 1214 // XXX We would prefer to just send a configuration version 1215 // XXX number such that the configuration can be identified 1216 // XXX that was active XXX when the report was generated. It 1217 // XXX would be nice to have a generic configuration version 1218 // XXX number that we could reuse. If this works out, we can 1219 // XXX inline the grouping as well. 1221 // XXX Note that task-grouping contains stuff that is not 1222 // XXX relevant here, perhaps using a grouping is not helpful 1223 // XXX here. It is also missing stuff, such as the options 1224 // XXX in the schedule entry. 1226 container header { 1227 description 1228 "The header of the result records."; 1230 leaf-list column { 1231 type string; 1232 description 1233 "A header of a column in the result rows."; 1234 } 1235 } 1237 list row { 1238 description 1239 "The rows of the result record."; 1241 leaf start { 1242 type yang:date-and-time; 1243 mandatory true; 1244 description 1245 "The date and time when the measurement producing 1246 this result row started."; 1247 } 1249 leaf end { 1250 type yang:date-and-time; 1251 description 1252 "The date and time when the measurement producing 1253 this result row stopped."; 1254 } 1256 leaf-list conflict { 1257 type string; 1258 description 1259 "The name of a task overlapping with the execution 1260 of the task that has produced this result record."; 1262 } 1264 leaf-list value { 1265 type string; 1266 description 1267 "The value of a cell in the result."; 1268 // XXX We could make this a union / choice in order to a 1269 // XXX more compact encoding of numbers in certain encodings 1270 // XXX (e.g. JSON) 1271 } 1272 } 1273 } 1274 } 1275 1277 5. Security Considerations 1279 TBD 1281 6. IANA Considerations 1283 This document registers a URI in the "IETF XML Registry" [RFC3688]. 1284 Following the format in RFC 3688, the following registrations have 1285 been made. 1287 URI: urn:ietf:params:xml:ns:yang:ietf-lmap-control 1288 Registrant Contact: The IESG. 1289 XML: N/A; the requested URI is an XML namespace. 1291 URI: urn:ietf:params:xml:ns:yang:ietf-lmap-report 1292 Registrant Contact: The IESG. 1293 XML: N/A; the requested URI is an XML namespace. 1295 This document registers a YANG module in the "YANG Module Names" 1296 registry [RFC6020]. 1298 name: ietf-lmap-control 1299 namespace: urn:ietf:params:xml:ns:yang:ietf-lmap-control 1300 prefix: lmapc 1301 reference: RFC XXXX 1303 name: ietf-lmap-report 1304 namespace: urn:ietf:params:xml:ns:yang:ietf-lmap-report 1305 prefix: lmapr 1306 reference: RFC XXXX 1308 7. Acknowledgements 1310 Juergen Schoenwaelder and Vaibhav Bajpai work in part on the Leone 1311 research project, which receives funding from the European Union 1312 Seventh Framework Programme [FP7/2007-2013] under grant agreement 1313 number 317647. 1315 8. References 1317 8.1. Normative References 1319 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1320 Requirement Levels", BCP 14, RFC 2119, March 1997. 1322 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1323 Network Configuration Protocol (NETCONF)", RFC 6020, 1324 October 2010. 1326 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 1327 July 2013. 1329 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1330 Management", RFC 7223, May 2014. 1332 8.2. Informative References 1334 [I-D.ietf-lmap-framework] 1335 Eardley, P., Morton, A., Bagnulo, M., Burbridge, T., 1336 Aitken, P., and A. Akhter, "A framework for Large-Scale 1337 Measurement of Broadband Performance (LMAP)", draft-ietf- 1338 lmap-framework-12 (work in progress), March 2015. 1340 [I-D.ietf-lmap-information-model] 1341 Burbridge, T., Eardley, P., Bagnulo, M., and J. 1342 Schoenwaelder, "Information Model for Large-Scale 1343 Measurement Platforms (LMAP)", draft-ietf-lmap- 1344 information-model-06 (work in progress), July 2015. 1346 [I-D.ietf-netconf-server-model] 1347 Watsen, K. and J. Schoenwaelder, "NETCONF Server and 1348 RESTCONF Server Configuration Models", draft-ietf-netconf- 1349 server-model-06 (work in progress), February 2015. 1351 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1352 January 2004. 1354 Appendix A. Open Issues 1356 o The task-options-grouping needs fixing, see the comments inline. 1358 o Should results be shipped via notifications or would it be more 1359 practical to have a collector provding a RESTCONF server and data 1360 is simply written via posts to suitable resources? This seems to 1361 be the way current platforms work. If we do this, we also need to 1362 think about how RESTCONF client credentials are configured. 1364 Appendix B. Non-editorial Changes since -06 1366 o A task can now reference multiply registry entries. 1368 o Schedules are triggered by Events instead of Timings; Timings are 1369 just one of many possible event sources. 1371 o Actions feed into other Schedules (instead of Actions within other 1372 Schedules). 1374 o Removed the notion of multiple task outputs. 1376 o Support for sequential, parallel, and pipelined execution of 1377 Actions. 1379 Appendix C. Example Configuration (XML) 1381 1382 1384 1385 550e8400-e29b-41d4-a716-446655440000 1386 urn:dev:mac:0024befffe804ff1 1387 wireless measurement at the north-pole 1388 true 1389 1391 1392 1393 hourly-schedule 1394 hourly 1395 1396 icmp-latency-hourly 1397 icmp-latency-measurement 1398 daily 1399 1400 1401 udp-latency-weekdays-hourly 1402 udp-latency-measurement 1403 daily 1404 1405 sequential 1406 1408 1409 daily-schedule 1410 daily 1411 1412 report-daily 1413 lmap-reporting-task 1414 1418 1419 sequential 1420 1422 1423 immediate-schedule 1424 immediate 1425 1426 icmp-latency-immediate 1427 icmp-latency-measurement 1428 1429 1430 report-immediate 1431 lmap-reporting-task 1432 1436 1437 pipelined 1438 1439 1440 1441 true 1442 2015-09-02T14:06:11+02:00 1443 iperf-server 1444 hourly 1445 weekdays-hourly 1446 1448 1449 1450 udp-latency-measurement 1451 urn:.... 1452 1453 1454 icmp-latency-measurement 1455 urn:.... 1456 1457 1458 iperf-server 1459 /usr/bin/iperf 1460 1464 false 1465 1466 1467 lmap-reporting-task 1468 /usr/bin/lmap-reporter 1469 1470 1472 1473 1474 hourly 1475 1476 3600000 1477 2014-09-01T17:44:00+02:00 1478 2015-09-30T00:00:00+02:00 1479 1480 1481 1482 daily 1483 1484 4 1485 1486 1487 1488 once-every-six-hours 1489 1490 0 1491 6 1492 12 1493 18 1494 0 1495 0 1496 2014-09-30T00:00:00+02:00 1497 1498 21600000 1499 1500 1501 immediate 1502 1503 1504 1505 startup 1506 1507 12345 1508 1509 1511 1513 1515 1516 550e8400-e29b-41d4-a716-446655440000 1517 urn:dev:mac:0024befffe804ff1 1518 ACME home router 1519 OpenWrt version 10.03.1 1520 Measurement Agent Daemon (MAD) 4.2 1521 2015-04-10T17:24:42+02:00 1522 1524 1525 1526 udp-latency-measurement 1527 urn:.... 1528 1530 1531 icmp-latency-measurement 1532 urn:.... 1533 1535 1536 iperf 1537 iperf 1538 1540 1541 lmap-reporting-task 1542 lmap-reportd 1543 2015-01-23T12:00:00+01:00 1544 0 1545 OK 1546 2015-01-23T03:00:00+01:00 1547 42 1548 connection timed out 1549 1550 1552 1553 1555 Appendix D. Example Configuration (JSON) 1557 { 1558 "ietf-lmap-control:lmap": { 1559 "agent": { 1560 "agent-id": "550e8400-e29b-41d4-a716-446655440000", 1561 "device-id": "urn:dev:mac:0024befffe804ff1", 1562 "group-id": "wireless measurement at the north-pole", 1563 "report-agent-id": true 1564 }, 1565 "schedules": { 1566 "schedule": [ 1567 { 1568 "name": "hourly-schedule", 1569 "event": "hourly", 1570 "action": [ 1571 { 1572 "name": "icmp-latency-hourly", 1573 "task": "icmp-latency-measurement", 1574 "destination": [ 1575 "daily" 1576 ] 1577 }, 1578 { 1579 "name": "udp-latency-weekdays-hourly", 1580 "task": "udp-latency-measurement", 1581 "destination": [ 1582 "daily" 1583 ] 1584 } 1585 ], 1586 "execution-mode": "sequential" 1587 }, 1588 { 1589 "name": "daily-schedule", 1590 "event": "daily", 1591 "action": [ 1592 { 1593 "name": "report-daily", 1594 "task": "lmap-reporting-task", 1595 "option": [ 1596 { 1597 "name": "channel", 1598 "value": "http://collector.example.org/" 1599 } 1600 ] 1601 } 1602 ], 1603 "execution-mode": "sequential" 1604 }, 1605 { 1606 "name": "immediate-schedule", 1607 "event": "immediate", 1608 "action": [ 1609 { 1610 "name": "icmp-latency-immediate", 1611 "task": "icmp-latency-measurement" 1612 }, 1613 { 1614 "name": "report-immediate", 1615 "task": "lmap-reporting-task", 1616 "option": [ 1617 { 1618 "name": "channel", 1619 "value": "http://collector.example.org/" 1620 } 1621 ] 1622 } 1623 ], 1624 "execution-mode": "pipelined" 1625 } 1626 ] 1627 }, 1628 "suppression": { 1629 "enabled": true, 1630 "start": "2015-09-02T14:06:11+02:00", 1631 "task": [ 1632 "iperf-server" 1633 ], 1634 "schedule": [ 1635 "hourly", 1636 "weekdays-hourly" 1637 ] 1638 }, 1639 "tasks": { 1640 "task": [ 1641 { 1642 "name": "udp-latency-measurement", 1643 "registry": [ 1644 "urn:...." 1645 ] 1646 }, 1647 { 1648 "name": "icmp-latency-measurement", 1649 "registry": [ 1650 "urn:...." 1651 ] 1652 }, 1653 { 1654 "name": "iperf-server", 1655 "program": "/usr/bin/iperf", 1656 "option": [ 1657 { 1658 "name": "role", 1659 "value": "server" 1660 } 1661 ], 1662 "suppress-by-default": false 1663 }, 1664 { 1665 "name": "lmap-reporting-task", 1666 "program": "/usr/bin/lmap-reporter" 1667 } 1668 ] 1669 }, 1670 "events": { 1671 "event": [ 1672 { 1673 "name": "hourly", 1674 "periodic": { 1675 "interval": 3600000, 1676 "start": "2014-09-01T17:44:00+02:00", 1677 "end": "2015-09-30T00:00:00+02:00" 1679 } 1680 }, 1681 { 1682 "name": "daily", 1683 "calendar": { 1684 "hour": [ 1685 4 1686 ] 1687 } 1688 }, 1689 { 1690 "name": "once-every-six-hours", 1691 "calendar": { 1692 "hour": [ 1693 0, 1694 6, 1695 12, 1696 18 1697 ], 1698 "minute": [ 1699 0 1700 ], 1701 "second": [ 1702 0 1703 ], 1704 "end": "2014-09-30T00:00:00+02:00" 1705 }, 1706 "random-spread": 21600000 1707 }, 1708 { 1709 "name": "immediate", 1710 "immediate": [null] 1711 }, 1712 { 1713 "name": "startup", 1714 "startup": [null], 1715 "random-spread": 12345 1716 } 1717 ] 1718 } 1719 }, 1720 "ietf-lmap-control:lmap-state": { 1721 "agent": { 1722 "agent-id": "550e8400-e29b-41d4-a716-446655440000", 1723 "device-id": "urn:dev:mac:0024befffe804ff1", 1724 "hardware": "ACME home router", 1725 "firmware": "OpenWrt version 10.03.1", 1726 "version": "Measurement Agent Daemon (MAD) 4.2", 1727 "last-started": "2015-04-10T17:24:42+02:00" 1728 }, 1729 "tasks": { 1730 "task": [ 1731 { 1732 "name": "udp-latency-measurement", 1733 "registry": [ 1734 "urn:...." 1735 ] 1736 }, 1737 { 1738 "name": "icmp-latency-measurement", 1739 "registry": [ 1740 "urn:...." 1741 ] 1742 }, 1743 { 1744 "name": "iperf", 1745 "program": "iperf" 1746 }, 1747 { 1748 "name": "lmap-reporting-task", 1749 "program": "lmap-reportd", 1750 "last-completion": "2015-01-23T12:00:00+01:00", 1751 "last-status": 0, 1752 "last-message": "OK", 1753 "last-failed-completion": "2015-01-23T03:00:00+01:00", 1754 "last-failed-status": 42, 1755 "last-failed-message": "connection timed out" 1756 } 1757 ] 1758 } 1759 } 1760 } 1762 Authors' Addresses 1764 Juergen Schoenwaelder 1765 Jacobs University Bremen 1767 Email: j.schoenwaelder@jacobs-university.de 1769 Vaibhav Bajpai 1770 Jacobs University Bremen 1772 Email: v.bajpai@jacobs-university.de