idnits 2.17.1 draft-schoenw-lmap-yang-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 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 163 has weird spacing: '...nterval uin...' == Line 191 has weird spacing: '...vice-id ine...' == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (January 23, 2015) is 3378 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-10 == Outdated reference: A later version (-18) exists of draft-ietf-lmap-information-model-03 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: July 27, 2015 January 23, 2015 7 A YANG Data Model for LMAP Measurement Agents 8 draft-schoenw-lmap-yang-02.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 July 27, 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 Module . . . . . . . . . . . . . . . . . . . . . . . . . 7 56 5. Security Considerations . . . . . . . . . . . . . . . . . . . 27 57 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 58 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 27 59 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 27 60 8.1. Normative References . . . . . . . . . . . . . . . . . . 27 61 8.2. Informative References . . . . . . . . . . . . . . . . . 28 62 Appendix A. Example Configuration (XML) . . . . . . . . . . . . 28 63 Appendix B. Example Configuration (JSON) . . . . . . . . . . . . 32 64 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 38 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 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 schedules 117 | +--rw schedule* [name] 118 | +--rw name string 119 | +--rw action* [name] 120 | | +--rw name string 121 | | +--rw task -> /lmap/tasks/task/name 122 | | +--rw option* [name] 123 | | | +--rw name string 124 | | | +--rw value? string 125 | | +--rw destination* [name] 126 | | +--rw name string 127 | | +--rw output* uint16 128 | | +--rw schedule -> /lmap/schedules/schedule/name 129 | | +--rw action -> /lmap/schedules/schedule[name = current()/../schedule]/action/name 130 | +--rw timing -> /lmap/timings/timing/name 131 +--rw suppression 132 | +--rw enabled? boolean 133 | +--rw stop-ongoing-tasks? boolean 134 | +--rw start? yang:date-and-time 135 | +--rw end? yang:date-and-time 136 | +--rw task* -> /lmap/tasks/task/name 137 | +--rw schedule* -> /lmap/schedules/schedule/name 138 +--rw channels 139 | +--rw channel* [name] 140 | +--rw name string 141 | +--rw url? inet:uri 142 | +--rw credentials? string 143 | +--rw interface? -> /if:interfaces/interface/name 144 +--rw tasks 145 | +--rw task* [name] 146 | +--rw name string 147 | +--rw (task-identification) 148 | | +--:(registry) 149 | | | +--rw registry? inet:uri 150 | | +--:(program) 151 | | +--rw program? string 152 | +--rw option* [name] 153 | | +--rw name string 154 | | +--rw value? string 155 | +--rw tag* string 156 | +--rw suppress-by-default? boolean 157 +--rw timings 158 +--rw timing* [name] 159 +--rw name string 160 +--rw (timing-type)? 161 | +--:(periodic) 162 | | +--rw periodic 163 | | +--rw interval uint32 164 | | +--rw start? yang:date-and-time 165 | | +--rw end? yang:date-and-time 166 | +--:(calendar) 167 | | +--rw calendar 168 | | +--rw month* month 169 | | +--rw weekday* weekday 170 | | +--rw day-of-months* int8 171 | | +--rw hour* int8 172 | | +--rw minute* int8 173 | | +--rw second* int8 174 | | +--rw timezone-offset? timezone-offset 175 | | +--rw start? yang:date-and-time 176 | | +--rw end? yang:date-and-time 177 | +--:(one-off) 178 | | +--rw one-off-time yang:date-and-time 179 | +--:(immediate) 180 | | +--rw immediate empty 181 | +--:(startup) 182 | +--rw startup empty 183 +--rw random-spread? int32 185 The tree diagram below shows the structure of the state model. 187 module: ietf-lmap 188 +--ro lmap-state 189 +--ro agent 190 | +--ro agent-id yang:uuid 191 | +--ro device-id inet:uri 192 | +--ro hardware string 193 | +--ro firmware string 194 | +--ro version string 195 +--ro tasks 196 +--ro task* [name] 197 +--ro name string 198 +--ro (task-identification) 199 | +--:(registry) 200 | | +--ro registry? inet:uri 201 | +--:(program) 202 | +--ro program? string 203 +--ro last-execution? yang:date-and-time 204 +--ro last-status? string 205 +--ro last-message? string 206 +--ro last-failed-execution? yang:date-and-time 207 +--ro last-failed-status? string 208 +--ro last-failed-message? string 210 The tree diagram below shows the structure of the notification 211 (reporting) model. 213 notifications: 214 +---n report 215 +--ro date yang:date-and-time 216 +--ro agent-id? yang:uuid 217 +--ro group-id? string 218 +--ro task* [name] 219 | +--ro name string 220 | +--ro (task-identification) 221 | | +--:(registry) 222 | | | +--ro registry? inet:uri 223 | | +--:(program) 224 | | +--ro program? string 225 | +--ro option* [name] 226 | | +--ro name string 227 | | +--ro value? string 228 | +--ro tag* string 229 | +--ro suppress-by-default? boolean 230 +--ro header 231 | +--ro column* string 232 +--ro row* 233 +--ro start yang:date-and-time 234 +--ro end? yang:date-and-time 235 +--ro conflict* string 236 +--ro cross-traffic? uint64 237 +--ro value* string 239 3. Relationship to the Information Model 241 The LMAP information model [I-D.ietf-lmap-information-model] is 242 devided into six sections. They are mapped into the YANG data model 243 as explained below: 245 o Pre-Configuration Information: This is not modeled explicitly 246 since it is a subset of the configuration information. 248 o Configuration Information: This is modeled in the /lmap/agent 249 subtree and the /lmap/schedules, /lmap/tasks, and /lmap/channels 250 subtrees described below. Some items have been left out because 251 they are expected to be dealt with by the underlying protocol. 253 o Instruction Information: This is modeled in the /lmap/suppression 254 subtree and the /lmap/schedules, /lmap/tasks, and /lmap/channels 255 subtrees described below. 257 o Logging Information: Some of the logging information, in 258 particular 'success/failure/warning messages in response to 259 information updates from the Controller', will be handled by the 260 protocol used to manipulate the lmap specific configuration. 261 [[CREF1: It needs to be discussed whether we can rely on informal 262 syslog messages that can be accessed via protocols such RFC 5277 263 or whether we want to define specific notifications in the YANG 264 data model. --JS]] 266 o Capability and Status Information: Some of the status information 267 is modeled in the /lmap-state/agent subtree. Information about 268 network interfaces can be obtained from the interfaces YANG data 269 model [RFC7223]. The list of supported tasks is modeled in the 270 /lmap-state/tasks subtree including information about the last 271 execution and the last failed execution. 273 o Reporting Information: This is modeled by the report notification. 275 These six sections are build on the following common information 276 objects: 278 o Schedules: This is modeled in the /lmap/schedules subtree. 280 o Channels: This is modeled in the /lmap/channels subtree. 282 o Task Configurations: This is modeled in the /lmap/tasks subtree. 284 o Timing Information: This is modeled in the /lmap/timings subtree. 286 4. YANG Module 288 This module imports definitions from [RFC6991] and [RFC7223]. 290 file "ietf-lmap@2015-01-23.yang" 291 module ietf-lmap { 293 namespace "urn:ietf:params:xml:ns:yang:ietf-lmap"; 294 prefix "lmap"; 296 import ietf-yang-types { 297 prefix yang; 298 } 299 import ietf-inet-types { 300 prefix inet; 301 } 302 import ietf-interfaces { 303 prefix if; 304 } 306 organization 307 "IETF Large-Scale Measurement Platforms Working Group"; 309 contact 310 "WG Web: 311 WG List: 313 Editor: Juergen Schoenwaelder 314 316 Editor: Vaibhav Bajpai 317 "; 319 description 320 "This module defines a data model for Large-Scale Measurement 321 Platforms (LMAP)."; 323 revision "2015-01-23" { 324 description 325 "Initial version"; 326 reference 327 "RFC XXX: A YANG Data Model for LMAP Measurement Agents"; 328 } 330 /* 331 * Typedefs 332 */ 334 typedef weekday { 335 type enumeration { 336 enum sunday { 337 description "Sunday of the week"; 338 } 339 enum monday { 340 description "Monday of the week"; 341 } 342 enum tuesday { 343 description "Tuesday of the week"; 344 } 345 enum wednesday { 346 description "Wednesday of the week"; 347 } 348 enum thursday { 349 description "Thursday of the week"; 350 } 351 enum friday { 352 description "Friday of the week"; 353 } 354 enum saturdary { 355 description "Saturday of the week"; 356 } 357 } 358 description 359 "A type modeling the weekdays in the Greco-Roman 360 tradition."; 361 } 363 typedef month { 364 type enumeration { 365 enum january { 366 description "January of the Julian and Gregorian calendar"; 367 } 368 enum february { 369 description "February of the Julian and Gregorian calendar"; 370 } 371 enum march { 372 description "March of the Julian and Gregorian calendar"; 373 } 374 enum april { 375 description "April of the Julian and Gregorian calendar"; 376 } 377 enum may { 378 description "May of the Julian and Gregorian calendar"; 379 } 380 enum june { 381 description "June of the Julian and Gregorian calendar"; 382 } 383 enum july { 384 description "July of the Julian and Gregorian calendar"; 385 } 386 enum august { 387 description "August of the Julian and Gregorian calendar"; 388 } 389 enum september { 390 description "September of the Julian and Gregorian calendar"; 391 } 392 enum october { 393 description "October of the Julian and Gregorian calendar"; 394 } 395 enum november { 396 description "November of the Julian and Gregorian calendar"; 397 } 398 enum december { 399 description "December of the Julian and Gregorian calendar"; 400 } 401 } 402 description 403 "A type modeling the month in the Julian and Gregorian 404 tradition."; 405 } 407 typedef timezone-offset { 408 type string { 409 pattern 'Z|[\+\-]\d{2}:\d{2}'; 410 } 411 description 412 "A timezone-offset as it is use in the yang:date-and-time 413 type. The value Z is equivalent to +00:00. The value -00:00 414 indicates and unknown time-offset."; 415 } 417 /* 418 * Groupings 419 */ 421 grouping timing-start-end-grouping { 422 description 423 "A grouping that provides start and end times for 424 timing objects."; 425 leaf start { 426 type yang:date-and-time; 427 description 428 "The date and time when the timing object 429 starts to create triggers."; 430 } 431 leaf end { 432 type yang:date-and-time; 433 description 434 "The date and time when the timing object 435 stops to create triggers. 437 It is generally a good idea to always configure 438 an end time and to refresh the configuration 439 of timing object as needed to ensure that agents 440 that loose connectivity to their controller 441 do not continue their tasks forever."; 442 } 443 } 445 grouping task-options-grouping { 446 description 447 "A list of options of a task. Each option is a name/value 448 pair (where the value may be absent)."; 450 list option { 451 key "name"; 452 ordered-by user; 454 description 455 "A list of options passed to the task. It is a list of 456 key / value pairs and may be used to model options. 457 Options may be used to identify the role of a task 458 or to pass a channel name to a task."; 460 leaf name { 461 type string; 462 description 463 "The name of the option."; 464 } 466 leaf value { 467 type string; 468 description 469 "The value of the option."; 470 } 471 } 472 } 474 grouping task-grouping { 475 description 476 "A grouping that defines the configuration of a task."; 478 list task { 479 key name; 480 description 481 "The list of tasks configured on the LMAP agent."; 483 leaf name { 484 type string; 485 description 486 "The unique name of a task."; 487 } 489 choice task-identification { 490 mandatory true; 491 description 492 "Information that identifies the task."; 494 leaf registry { 495 type inet:uri; 496 description 497 "The registry entry identifying the configured task."; 498 } 499 leaf program { 500 type string; 501 description 502 "The (local) program to invoke in order to execute 503 the task."; 504 } 505 } 507 uses task-options-grouping { 508 description 509 "The list of task specific options."; 510 } 512 leaf-list tag { 513 type string; 514 description 515 "A tag contains additional information that is passed 516 with the result record to the collector. A tag can be 517 used to carry the Measurement Cycle ID."; 518 } 520 leaf suppress-by-default { 521 type boolean; 522 default true; 523 description 524 "Indicates whether the task will be suppressed by 525 a default supression."; 526 } 527 } 528 } 530 /* 531 * Configuration data nodes 532 */ 534 container lmap { 535 description 536 "Configuration of the LMAP agent."; 538 /* 539 * Common Information Objects: Configuration 540 */ 542 container agent { 543 description 544 "Configuration of parameters affecting the whole 545 measurement agent."; 547 leaf agent-id { 548 type yang:uuid; 549 description 550 "The agent-id identifies a measurement agent with 551 a very low probability of collision. In certain 552 deployments, the agent-id may be considered 553 sensitive and hence this object is optional."; 554 } 556 leaf device-id { 557 type inet:uri; 558 description 559 "The device-id identifies a property of the 560 device running the measurement agent. In certain 561 deployments, the device-id may be considered 562 sensitive and hence this object is optional."; 563 } 565 leaf credentials { 566 type string; 567 description 568 "The credentials of the agent."; 569 // XXX: This is way too simplistic. Credentials are 570 // specific to the authentication mechanism used 571 // by a protocol. Hence, this needs to be a far 572 // more complex and extensible choice or it might 573 // not be needed since the protocol data models 574 // already cover it. 575 } 577 leaf group-id { 578 type string; 579 description 580 "The group-id identifies a group of measurement 581 agents. In certain deployments, the group-id 582 may be considered less sensitive than the 583 agent-id."; 584 } 586 leaf report-agent-id { 587 type boolean; 588 default false; 589 // XXX: write a must expression that requires 590 // group-id to be configured when this is true? 591 description 592 "The 'report-agent-id' controls whether the 593 'agent-id' is reported to collectors if the 594 'group-id' is configured. If the 'group-id' 595 is not configured, the agent-id is always 596 reported."; 597 } 598 } 600 /* 601 * Common Information Objects: Schedules 602 */ 604 container schedules { 605 description 606 "Configuration of LMAP schedules. Schedules control with 607 tasks are executed by the LMAP implementation."; 609 list schedule { 610 key name; 611 description 612 "Configuration of a particular schedule."; 614 leaf name { 615 type string; 616 description 617 "The locally-unique, administratively assigned name for 618 this scheduled task."; 619 } 621 list action { 622 key name; 623 description 624 "An action describes a task that is invoked by the 625 schedule. Multiple actions are invoked sequentially."; 627 leaf name { 628 type string; 629 description 630 "The unique identifier for this action."; 631 } 633 leaf task { 634 type leafref { 635 path "/lmap/tasks/task/name"; 636 } 637 mandatory true; 638 description 639 "The tasks invoked by this action."; 640 } 642 uses task-options-grouping { 643 description 644 "The list of action specific options that are 645 appended to the list of task specific options."; 646 } 648 list destination { 649 key "name"; 650 description 651 "A destination receives information from the task 652 associated with this action. A queue is internally 653 used to pass the information to another (scheduled) 654 action."; 656 leaf name { 657 type string; 658 description 659 "The name of this destination (queue) that passes 660 information to another (scheduled) action."; 661 } 663 leaf-list output { 664 type uint16; 665 description 666 "The list of outputs of a task directed to another 667 (scheduled) action. If no output is specified, 668 then all output is directed to another (scheduled) 669 action."; 670 } 672 leaf schedule { 673 type leafref { 674 path "/lmap/schedules/schedule/name"; 675 } 676 mandatory true; 677 description 678 "The schedule of the (scheduled) action receiving 679 the output."; 680 } 682 leaf action { 683 type leafref { 684 path "/lmap/schedules/schedule" 685 + "[name = current()/../schedule]" 686 + "/action/name"; 687 } 688 mandatory true; 689 description 690 "The (scheduled) action receiving the output (the 691 destination consuming the data from the queue)."; 692 } 693 } 694 } 696 leaf timing { 697 type leafref { 698 path "/lmap/timings/timing/name"; 699 } 700 mandatory true; 701 description 702 "The timing source controlling the start of the scheduled 703 tasks."; 704 } 705 } 706 } 708 /* 709 * Suppression 710 */ 712 container suppression { 713 description 714 "Suppression information to prevent schedules to start 715 certain tasks."; 717 leaf enabled { 718 type boolean; 719 default false; 720 description 721 "Setting 'enabled' to true will suppress all tasks that 722 where suppress-by-default is true."; 723 } 725 leaf stop-ongoing-tasks { 726 type boolean; 727 default false; 728 description 729 "Setting 'stop-ongoing-tasks' to true will cause 730 running tasks to be terminated if 'enabled' is set 731 to true. Otherwise, running tasks will not be 732 affected."; 733 } 735 leaf start { 736 type yang:date-and-time; 737 description 738 "The date and time when supression starts to 739 become effective. If not present, supression 740 becomes effective immeditately when 'enabled' 741 is set to true."; 742 } 744 leaf end { 745 type yang:date-and-time; 746 description 747 "The date and time when supression stops to 748 be effective. If not present, supression 749 continues indefinite until 'enabled' is set 750 to false."; 751 } 753 leaf-list task { 754 type leafref { 755 path "/lmap/tasks/task/name"; 756 } 757 description 758 "A specific task to suppress. If no tasks are 759 listed, then all tasks will be suppressed."; 760 } 762 leaf-list schedule { 763 type leafref { 764 path "/lmap/schedules/schedule/name"; 765 } 766 description 767 "A specific schedule to suppress. If no schedules 768 are listed, then all schedules will be suppressed."; 769 } 771 } 773 /* 774 * Common Information Objects: Channels 775 */ 777 container channels { 778 description 779 "A channel describes properties of an LMAP control or 780 reporting channel."; 782 list channel { 783 key name; 784 description 785 "The list of channels configured on the LMAP agent."; 787 leaf name { 788 type string; 789 description 790 "The unique name of a channel."; 791 } 793 leaf url { 794 type inet:uri; 795 description 796 "The remote endpoint of the channel."; 797 } 799 leaf credentials { 800 type string; 801 description 802 "The credentials of the channel."; 803 // XXX: This is way too simplistic. Credentials are 804 // specific to the authentication mechanism used 805 // by a protocol. Hence, this needs to be a far 806 // more complex and extensible choice. 807 } 809 leaf interface { 810 type leafref { 811 path "/if:interfaces/if:interface/if:name"; 812 } 813 description 814 "The local interface to use for reaching the remote 815 endpoint of the channel."; 816 } 817 } 818 } 820 /* 821 * Common Information Objects: Task Configurations 822 */ 824 container tasks { 825 description 826 "Configuration of LMAP tasks."; 828 uses task-grouping; 829 } 831 /* 832 * Common Information Objects: Timing Information 833 */ 835 container timings { 836 description 837 "Configuration of LMAP timings. 839 Implementations may be forced to delay acting 840 upon triggers in the face of local constraints. 841 A task triggered therefore not rely on the accuracy 842 provided by the scheduler implementation."; 844 list timing { 845 key name; 846 description 847 "The list of timings configured on the LMAP agent."; 849 leaf name { 850 type string; 851 description 852 "The unique name of a timing."; 853 } 855 choice timing-type { 856 description 857 "Different types of timing objects are handled by 858 different branches of this choices."; 860 case periodic { 861 container periodic { 862 description 863 "A periodic timing object triggers periodically 864 driven by a regular interval."; 866 leaf interval { 867 type uint32; 868 units "milliseconds"; 869 mandatory true; 870 description 871 "The number of milliseconds between two triggers 872 generated by this periodic timing object. 874 The execution system must not generate triggers 875 for periodic timing objects that have a interval 876 value of 0. A timing object with an interval of 877 0 milliseconds will therefore never trigger."; 878 } 879 uses timing-start-end-grouping; 880 } 881 } 882 case calendar { 883 container calendar { 884 description 885 "A calendar timing object trigger based on the 886 current calendar date and time."; 888 leaf-list month { 889 type month; 890 description 891 "A month at which this calendar timing will 892 trigger."; 893 } 894 leaf-list weekday { 895 type weekday; 896 description 897 "A weekday at which this calendar timing will 898 trigger."; 899 } 900 leaf-list day-of-months { 901 type int8 { 902 range "-31..-1 | 1..31"; 903 } 904 description 905 "A day in the months at which this calendar 906 timing will trigger. Negative numbers indicate 907 days counted backwards from the end of the 908 months."; 909 } 910 leaf-list hour { 911 type int8 { 912 range "0..23"; 913 } 914 description 915 "An hour at which this calendar timing will 916 trigger."; 917 } 918 leaf-list minute { 919 type int8 { 920 range "0..59"; 921 } 922 description 923 "A minute at which this calendar timing will 924 trigger."; 925 } 926 leaf-list second { 927 type int8 { 928 range "0..59"; 929 } 930 description 931 "A second at which this calendar timing will 932 trigger."; 933 } 934 leaf timezone-offset { 935 type timezone-offset; 936 description 937 "The timezone in which this calendar timing 938 object will be evaluated."; 939 } 940 uses timing-start-end-grouping; 941 } 942 } 943 case one-off { 944 leaf one-off-time { 945 type yang:date-and-time; 946 mandatory true; 947 description 948 "This one-off timing object triggers once at the 949 configured one-off-time."; 950 } 951 } 952 case immediate { 953 leaf immediate { 954 type empty; 955 mandatory true; 956 description 957 "This immediate timing object triggers immediately 958 when it is configured."; 959 } 960 } 961 case startup { 962 leaf startup { 963 type empty; 964 mandatory true; 965 description 966 "This startup timing object triggers whenever the 967 LMAP agent (re)starts."; 968 } 969 } 970 } 972 leaf random-spread { 973 type int32; 974 units milliseconds; 975 description 976 "This optional leaf adds a random spread to the 977 computation of the trigger."; 978 } 980 } 981 } 982 } 984 /* 985 * The state subtree provides information about the capabilities 986 * and the current status of the MA. 987 */ 989 container lmap-state { 990 config false; 991 description 992 "A tree exporting state information about the LMAP agent."; 994 container agent { 995 description 996 "Operations state of the measurement agent."; 998 leaf agent-id { 999 type yang:uuid; 1000 mandatory true; 1001 description 1002 "The agent-id identifies a measurement agent with 1003 a very low probability of collision. In certain 1004 deployments, the agent-id may be considered 1005 sensitive and hence this object is optional."; 1006 } 1008 leaf device-id { 1009 type inet:uri; 1010 mandatory true; 1011 description 1012 "The device-id identifies a property of the 1013 device running the measurement agent. In certain 1014 deployments, the device-id may be considered 1015 sensitive and hence this object is optional."; 1016 } 1017 leaf hardware { 1018 type string; 1019 mandatory true; 1020 description 1021 "A short description of the hardware the measurement 1022 agent is running on. This should include the version 1023 number of the hardware"; 1024 } 1025 leaf firmware { 1026 type string; 1027 mandatory true; 1028 description 1029 "A short description of the firmware the measurement 1030 agent is running on. This should include the version 1031 number of the firmware."; 1032 } 1033 leaf version { 1034 type string; 1035 mandatory true; 1036 description 1037 "A short description of the software implementing the 1038 measurement agent. This should include the version 1039 number of the measurement agent software."; 1040 } 1041 } 1043 container tasks { 1044 description 1045 "Available LMAP tasks, including information about their 1046 last execution and their last failed execution."; 1048 list task { 1049 key name; 1050 description 1051 "The list of tasks available on the LMAP agent."; 1053 leaf name { 1054 type string; 1055 description 1056 "The unique name of a task."; 1057 } 1059 choice task-identification { 1060 mandatory true; 1061 description 1062 "Information that identifies the task."; 1064 leaf registry { 1065 type inet:uri; 1066 description 1067 "The registry entry identifying the configured task."; 1068 } 1070 leaf program { 1071 type string; 1072 description 1073 "The (local) program to invoke in order to execute 1074 the task."; 1075 } 1077 } 1079 leaf last-execution { 1080 type yang:date-and-time; 1081 description 1082 "The date and time of the last invocation of this task."; 1083 } 1085 leaf last-status { 1086 type string; // XXX should this be an enum? 1087 description 1088 "The status code returned by the last execution of 1089 this task."; 1090 } 1092 leaf last-message { 1093 type string; 1094 description 1095 "The status message produced by the last execution 1096 of this task."; 1097 } 1099 leaf last-failed-execution { 1100 type yang:date-and-time; 1101 description 1102 "The date and time of the last failed invocation 1103 of this task."; 1104 } 1106 leaf last-failed-status { 1107 type string; // XXX should this be an enum? 1108 description 1109 "The status code returned by the last failed execution 1110 of this task."; 1111 } 1113 leaf last-failed-message { 1114 type string; 1115 description 1116 "The status message produced by the last failed 1117 execution of this task."; 1118 } 1119 } 1120 } 1121 } 1123 notification report { 1124 description 1125 "The result record produced by a certain task."; 1127 leaf date { 1128 type yang:date-and-time; 1129 mandatory true; 1130 description 1131 "The date and time when this report was sent."; 1132 } 1134 leaf agent-id { 1135 type yang:uuid; 1136 description 1137 "The agent-id of the agent from which this 1138 report originates."; 1139 } 1141 leaf group-id { 1142 type string; 1143 description 1144 "The group-id of the agent from which this 1145 report originates."; 1146 } 1148 uses task-grouping; 1149 // XXX We would prefer to just send a configuration version 1150 // XXX number such that the configuration can be identified 1151 // XXX that was active XXX when the report was generated. It 1152 // XXX would be nice to have a generic configuration version 1153 // XXX number that we could reuse. If this works out, we can 1154 // XXX inline the grouping as well. 1156 container header { 1157 description 1158 "The header of the result records."; 1160 leaf-list column { 1161 type string; 1162 description 1163 "A header of a column in the result rows."; 1164 } 1165 } 1167 list row { 1168 description 1169 "The rows of the result record."; 1171 leaf start { 1172 type yang:date-and-time; 1173 mandatory true; 1174 description 1175 "The date and time when the measurement producing 1176 this result row started."; 1177 } 1179 leaf end { 1180 type yang:date-and-time; 1181 description 1182 "The date and time when the measurement producing 1183 this result row stopped."; 1184 } 1186 leaf-list conflict { 1187 // XXX: Unclear what this string contains since tasks 1188 // lifetime in config is different from result record 1189 // lifetime (buffering). 1190 type string; 1191 description 1192 "The name of a task overlapping with the execution 1193 of the task that has produced this result record."; 1194 } 1196 leaf cross-traffic { 1197 type uint64; 1198 description 1199 "The number of bytes of non-measurement traffic on 1200 the measurement interface(s) during the measurement 1201 period."; 1202 } 1204 leaf-list value { 1205 // XXX: Should this be a union? At the end, all is 1206 // a string. 1207 type string; 1208 description 1209 "The value of a cell in the result."; 1210 } 1211 } 1212 } 1213 } 1214 1216 5. Security Considerations 1218 TBD 1220 6. IANA Considerations 1222 This document registers a URI in the "IETF XML Registry" [RFC3688]. 1223 Following the format in RFC 3688, the following registrations have 1224 been made. 1226 URI: urn:ietf:params:xml:ns:yang:ietf-lmap 1227 Registrant Contact: The IESG. 1228 XML: N/A; the requested URI is an XML namespace. 1230 This document registers a YANG module in the "YANG Module Names" 1231 registry [RFC6020]. 1233 name: ietf-lmap 1234 namespace: urn:ietf:params:xml:ns:yang:ietf-lmap 1235 prefix: lmap 1236 reference: RFC XXXX 1238 7. Acknowledgements 1240 Juergen Schoenwaelder and Vaibhav Bajpai work in part on the Leone 1241 research project, which receives funding from the European Union 1242 Seventh Framework Programme [FP7/2007-2013] under grant agreement 1243 number 317647. 1245 8. References 1247 8.1. Normative References 1249 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1250 Requirement Levels", BCP 14, RFC 2119, March 1997. 1252 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1253 Network Configuration Protocol (NETCONF)", RFC 6020, 1254 October 2010. 1256 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 1257 July 2013. 1259 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1260 Management", RFC 7223, May 2014. 1262 8.2. Informative References 1264 [I-D.ietf-lmap-framework] 1265 Eardley, P., Morton, A., Bagnulo, M., Burbridge, T., 1266 Aitken, P., and A. Akhter, "A framework for large-scale 1267 measurement platforms (LMAP)", draft-ietf-lmap- 1268 framework-10 (work in progress), January 2015. 1270 [I-D.ietf-lmap-information-model] 1271 Burbridge, T., Eardley, P., Bagnulo, M., and J. 1272 Schoenwaelder, "Information Model for Large-Scale 1273 Measurement Platforms (LMAP)", draft-ietf-lmap- 1274 information-model-03 (work in progress), January 2015. 1276 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1277 January 2004. 1279 Appendix A. Example Configuration (XML) 1281 1282 1284 1285 550e8400-e29b-41d4-a716-446655440000 1286 urn:dev:mac:0024befffe804ff1 1287 wireless measurement at the north-pole 1288 true 1289 1291 1292 1293 weekdays-hourly 1294 1295 udp-latency-weekdays-hourly 1296 udp-latency-measurement 1297 1298 q-all 1299 daily 1300 report-daily 1301 1302 1303 hourly 1304 1305 1306 hourly 1307 1308 icmp-latency-hourly 1309 icmp-latency-measurement 1310 1311 q-all 1312 daily 1313 report-daily 1314 1315 1316 hourly 1317 1319 1320 daily 1321 1322 report-daily 1323 lmap-reporting-task 1324 1328 1329 daily 1330 1332 1333 immediate 1334 1335 icmp-latency-immediate 1336 icmp-latency-measurement 1337 1338 q-all 1339 immediate 1340 report-immediate 1341 1342 1343 1344 report-immediate 1345 lmap-reporting-task 1346 1350 1351 immediate 1352 1354 1355 1357 1358 true 1359 2014-09-02T14:06:11+02:00 1360 iperf-server 1361 hourly 1362 weekdays-hourly 1363 1365 1366 1367 default-collector-channel 1368 1369 1371 1372 1373 udp-latency-measurement 1374 urn:.... 1375 1376 1377 icmp-latency-measurement 1378 urn:.... 1379 1380 1381 iperf-server 1382 iperf 1383 1387 false 1388 1389 1390 lmap-reporting-task 1391 lmap-reportd 1392 1393 1395 1396 1397 hourly 1398 1399 3600000 1400 2014-09-01T17:44:00+02:00 1401 2014-09-30T00:00:00+02:00 1403 1404 1405 1406 daily 1407 1408 04 1409 1410 1411 1412 tuesday-thursday-sunday 1413 1414 tuesday 1415 thursday 1416 sunday 1417 18 1418 04 1419 42 1420 2014-09-30T00:00:00+02:00 1421 1422 1423 1424 once-every-six-hours 1425 1426 0 1427 6 1428 12 1429 18 1430 0 1431 0 1432 2014-09-30T00:00:00+02:00 1433 1434 21600000 1435 1436 1437 immediate 1438 1439 1440 1441 startup 1442 1443 12345 1444 1445 1447 1449 1450 1451 550e8400-e29b-41d4-a716-446655440000 1452 urn:dev:mac:0024befffe804ff1 1453 ACME home router 1454 OpenWrt version 10.03.1 1455 Measurement Agent Daemon (MAD) 4.2 1456 1458 1459 1460 udp-latency-measurement 1461 urn:.... 1462 1464 1465 icmp-latency-measurement 1466 urn:.... 1467 1469 1470 iperf 1471 iperf 1472 1474 1475 lmap-reporting-task 1476 lmap-reportd 1477 2015-01-23T12:00:00+01:00 1478 200 1479 OK 1480 2015-01-23T03:00:00+01:00 1481 503 1482 connection timed out 1483 1484 1486 1487 1489 Appendix B. Example Configuration (JSON) 1491 { 1492 "ietf-lmap:lmap": { 1493 "agent": { 1494 "agent-id": "550e8400-e29b-41d4-a716-446655440000", 1495 "device-id": "urn:dev:mac:0024befffe804ff1", 1496 "group-id": "wireless measurement at the north-pole", 1497 "report-agent-id": true 1498 }, 1499 "schedules": { 1500 "schedule": [ 1501 { 1502 "name": "weekdays-hourly", 1503 "action": [ 1504 { 1505 "name": "udp-latency-weekdays-hourly", 1506 "task": "udp-latency-measurement", 1507 "destination": [ 1508 { 1509 "name": "q-all", 1510 "schedule": "daily", 1511 "action": "report-daily" 1512 } 1513 ] 1514 } 1515 ], 1516 "timing": "hourly" 1517 }, 1518 { 1519 "name": "hourly", 1520 "action": [ 1521 { 1522 "name": "icmp-latency-hourly", 1523 "task": "icmp-latency-measurement", 1524 "destination": [ 1525 { 1526 "name": "q-all", 1527 "schedule": "daily", 1528 "action": "report-daily" 1529 } 1530 ] 1531 } 1532 ], 1533 "timing": "hourly" 1534 }, 1535 { 1536 "name": "daily", 1537 "action": [ 1538 { 1539 "name": "report-daily", 1540 "task": "lmap-reporting-task", 1541 "option": [ 1542 { 1543 "name": "channel", 1544 "value": "default-collector-channel" 1545 } 1546 ] 1547 } 1548 ], 1549 "timing": "daily" 1550 }, 1551 { 1552 "name": "immediate", 1553 "action": [ 1554 { 1555 "name": "icmp-latency-immediate", 1556 "task": "icmp-latency-measurement", 1557 "destination": [ 1558 { 1559 "name": "q-all", 1560 "schedule": "immediate", 1561 "action": "report-immediate" 1562 } 1563 ] 1564 }, 1565 { 1566 "name": "report-immediate", 1567 "task": "lmap-reporting-task", 1568 "option": [ 1569 { 1570 "name": "channel", 1571 "value": "default-collector-channel" 1572 } 1573 ] 1574 } 1575 ], 1576 "timing": "immediate" 1577 } 1578 ] 1579 }, 1580 "suppression": { 1581 "enabled": true, 1582 "start": "2014-09-02T14:06:11+02:00", 1583 "task": [ 1584 "iperf-server" 1585 ], 1586 "schedule": [ 1587 "hourly", 1588 "weekdays-hourly" 1589 ] 1590 }, 1591 "channels": { 1592 "channel": [ 1593 { 1594 "name": "default-collector-channel" 1595 } 1596 ] 1597 }, 1598 "tasks": { 1599 "task": [ 1600 { 1601 "name": "udp-latency-measurement", 1602 "registry": "urn:...." 1603 }, 1604 { 1605 "name": "icmp-latency-measurement", 1606 "registry": "urn:...." 1607 }, 1608 { 1609 "name": "iperf-server", 1610 "program": "iperf", 1611 "option": [ 1612 { 1613 "name": "role", 1614 "value": "server" 1615 } 1616 ], 1617 "suppress-by-default": false 1618 }, 1619 { 1620 "name": "lmap-reporting-task", 1621 "program": "lmap-reportd" 1622 } 1623 ] 1624 }, 1625 "timings": { 1626 "timing": [ 1627 { 1628 "name": "hourly", 1629 "periodic": { 1630 "interval": 3600000, 1631 "start": "2014-09-01T17:44:00+02:00", 1632 "end": "2014-09-30T00:00:00+02:00" 1633 } 1634 }, 1635 { 1636 "name": "daily", 1637 "calendar": { 1638 "hour": [ 1639 04 1641 ] 1642 } 1643 }, 1644 { 1645 "name": "tuesday-thursday-sunday", 1646 "calendar": { 1647 "weekday": [ 1648 "tuesday", 1649 "thursday", 1650 "sunday" 1651 ], 1652 "hour": [ 1653 18 1654 ], 1655 "minute": [ 1656 04 1657 ], 1658 "second": [ 1659 42 1660 ], 1661 "end": "2014-09-30T00:00:00+02:00" 1662 } 1663 }, 1664 { 1665 "name": "once-every-six-hours", 1666 "calendar": { 1667 "hour": [ 1668 0, 1669 6, 1670 12, 1671 18 1672 ], 1673 "minute": [ 1674 0 1675 ], 1676 "second": [ 1677 0 1678 ], 1679 "end": "2014-09-30T00:00:00+02:00" 1680 }, 1681 "random-spread": 21600000 1682 }, 1683 { 1684 "name": "immediate", 1685 "immediate": [null] 1686 }, 1687 { 1688 "name": "startup", 1689 "startup": [null], 1690 "random-spread": 12345 1691 } 1692 ] 1693 } 1694 }, 1695 "ietf-lmap:lmap-state": { 1696 "agent": { 1697 "agent-id": "550e8400-e29b-41d4-a716-446655440000", 1698 "device-id": "urn:dev:mac:0024befffe804ff1", 1699 "hardware": "ACME home router", 1700 "firmware": "OpenWrt version 10.03.1", 1701 "version": "Measurement Agent Daemon (MAD) 4.2" 1702 }, 1703 "tasks": { 1704 "task": [ 1705 { 1706 "name": "udp-latency-measurement", 1707 "registry": "urn:...." 1708 }, 1709 { 1710 "name": "icmp-latency-measurement", 1711 "registry": "urn:...." 1712 }, 1713 { 1714 "name": "iperf", 1715 "program": "iperf" 1716 }, 1717 { 1718 "name": "lmap-reporting-task", 1719 "program": "lmap-reportd", 1720 "last-execution": "2015-01-23T12:00:00+01:00", 1721 "last-status": "200", 1722 "last-message": "OK", 1723 "last-failed-execution": "2015-01-23T03:00:00+01:00", 1724 "last-failed-status": "503", 1725 "last-failed-message": "connection timed out" 1726 } 1727 ] 1728 } 1729 } 1730 } 1732 Authors' Addresses 1734 Juergen Schoenwaelder 1735 Jacobs University Bremen 1737 Email: j.schoenwaelder@jacobs-university.de 1739 Vaibhav Bajpai 1740 Jacobs University Bremen 1742 Email: v.bajpai@jacobs-university.de