Network Working Group A. Oslebo Internet-Draft UNINETT Intended status: Standards Track September 12, 2014 Expires: March 16, 2015 A YANG based Data Model for the LMAP Control Protocol draft-oslebo-lmap-control-yang-00.txt Abstract This document defines a YANG data model for the LMAP control protocol. The model is based on measurement agents polling information from a controller. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on March 16, 2015. Copyright Notice Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Oslebo Expires March 16, 2015 [Page 1] Internet-Draft LMAP Control Data Model September 2014 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Requirements notation . . . . . . . . . . . . . . . . . . 2 1.2. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 2 2. Data Model Overview . . . . . . . . . . . . . . . . . . . . . 3 3. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 5 4. Security Considerations . . . . . . . . . . . . . . . . . . . 21 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 21 6. Normative References . . . . . . . . . . . . . . . . . . . . 21 Appendix A. Example configuration . . . . . . . . . . . . . . . 21 Appendix B. RESTCONF queries . . . . . . . . . . . . . . . . . . 24 B.1. Get configuration - XML format . . . . . . . . . . . . . 24 B.2. Get schedules - JSON format . . . . . . . . . . . . . . . 24 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 25 1. Introduction The LMAP framework[I-D.ietf-lmap-framework] defines three main components: o Measurement Agents (MAs) - initiates the actual measurements. o Controller - controls one or more MAs. It instructs them when to do measurements and when and how to report the results. o Collector - accepts measurement results from MAs This document defines a YANG data model for the LMAP controller. The MAs will poll the information stored on the controller using the RESTCONF protocol[I-D.ietf-netconf-restconf]. A future draft will define a YANG model for the collector that will be used by the MAs to report the results. 1.1. Requirements notation The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. 1.2. Tree Diagrams A simplified graphical representation of the data model is used in this document. The meaning of the symbols in these diagrams is as follows: o Brackets "[" and "]" enclose list keys. Oslebo Expires March 16, 2015 [Page 2] Internet-Draft LMAP Control Data Model September 2014 o Abbreviations before data node names: "rw" means configuration (read-write), and "ro" means state data (read-only). o Symbols after data node names: "?" means an optional node, "!" means a presence container, and "*" denotes a list and leaf-list. o Parentheses enclose choice and case nodes, and case nodes are also marked with a colon (":"). o Ellipsis ("...") stands for contents of subtrees that are not shown. 2. Data Model Overview The data model first defines a set of common objects for tasks, channels, schedules, and timing definitions that are shared among all the MAs that are controlled by the controller. It then defines a list of MA objects that contains configuration specific for each MA. In the MA object there is a list of references to the common schedules and each reference represents an active schedule for this specific MA. module: lmap-control +--rw lmap-control +--rw tasks | +--rw task* [name] | +--rw name string | +--rw registry-entry inet:uri | +--rw role? string | +--rw options | | +--rw option* [name] | | +--rw name string | | +--rw value? string | +--rw suppress-by-default? boolean | +--rw cycle-id? string +--rw channels | +--rw channel* [name] | +--rw name string | +--rw target inet:uri | +--rw credentials string | +--rw interface-name? leafref +--rw schedules | +--rw schedule* [name] | +--rw name string | +--rw tasks | | +--rw task* [name] | | +--rw name leafref | | +--rw channels Oslebo Expires March 16, 2015 [Page 3] Internet-Draft LMAP Control Data Model September 2014 | | | +--rw channel* leafref | | +--rw downstream-schedules | | +--rw downstream-schedule* [schedule] | | +--rw schedule leafref | | +--rw outputs | | +--rw output* int32 | +--rw timing? leafref +--rw timings | +--rw timing* [name] | +--rw name string | +--rw (timing-type) | | +--:(periodic) | | | +--rw periodic | | | +--rw interval uint32 | | | +--rw start? yang:date-and-time | | | +--rw end? yang:date-and-time | | +--:(calendar) | | | +--rw calendar | | | +--rw month* month | | | +--rw weekday* weekday | | | +--rw day-of-months* int8 | | | +--rw hour* int8 | | | +--rw minute* int8 | | | +--rw second* int8 | | | +--rw timezone-offset? timezone-offset | | | +--rw start? yang:date-and-time | | | +--rw end? yang:date-and-time | | +--:(one-off) | | | +--rw one-off-time yang:date-and-time | | +--:(immediate) | | | +--rw immediate empty | | +--:(startup) | | +--rw startup empty | +--rw random-spread? int32 +--rw log | +--rw log-entry* [agent-id log-event-time] | +--rw agent-id leafref | +--rw log-event-time int64 | +--rw log-code int32 | +--rw log-description string +--rw measurement-agents +--rw ma* [agent-id] +--rw agent-id yang:uuid +--rw config | +--rw device-id? inet:uri | +--rw credentials string | +--rw group-id? string | +--rw report-id-flag? boolean Oslebo Expires March 16, 2015 [Page 4] Internet-Draft LMAP Control Data Model September 2014 | +--rw control-channel-failure-threshold? int32 +--rw schedules | +--rw schedule* leafref +--rw suppressions | +--rw enabled? boolean | +--rw stop-ongoing-tasks? boolean | +--rw start? yang:date-and-time | +--rw stop? yang:date-and-time | +--rw tasks | | +--rw task* leafref | +--rw schedules | +--rw schedule* leafref +--rw status-and-capabilities +--rw hardware? string +--rw firmware? string +--rw version? string +--rw interfaces | +--rw interface* leafref +--rw last-measurement? yang:date-and-time +--rw last-report? yang:date-and-time +--rw last-instruction? yang:date-and-time +--rw last-configuration? yang:date-and-time +--rw supported-tasks | +--rw supported-task* [name] | +--rw name string | +--rw registry inet:uri | +--rw role? string +--rw conditions +--rw condition* [code] +--rw code string +--rw text? string 3. YANG module file "lmap-control@2014-09-12" module lmap-control { namespace "urn:ietf:params:xml:ns:yang:lmap-control"; prefix "lmap-control"; import ietf-yang-types { prefix "yang"; } import ietf-inet-types { prefix "inet"; Oslebo Expires March 16, 2015 [Page 5] Internet-Draft LMAP Control Data Model September 2014 } import ietf-interfaces { prefix "if"; } organization "IETF Large-Scale Measurement Platforms Working Group"; contact "WG Web: WG List: Editor: Arne Oslebo "; description "This YANG module defines a data model for the control protocol for Large-Scale Measurement Platforms (LMAP). The information is stored on a LMAP controller and Measurement Agents will pull this information from the controller at predefined intervals."; revision 2014-09-12 { description "Initial revision."; reference "RFC XXX: A YANG Data Model for the LMAP control protocol"; } typedef weekday { type enumeration { enum sunday { description "Sunday of the week"; } enum monday { description "Monday of the week"; } enum tuesday { description "Tuesday of the week"; } enum wednesday { description "Wednesday of the week"; } enum thursday { description "Thursday of the week"; Oslebo Expires March 16, 2015 [Page 6] Internet-Draft LMAP Control Data Model September 2014 } enum friday { description "Friday of the week"; } enum saturdary { description "Saturday of the week"; } } description "A type modeling the weekdays in the Greco-Roman tradition."; } typedef month { type enumeration { enum january { description "January of the Julian and Gregorian calendar"; } enum february { description "February of the Julian and Gregorian calendar"; } enum march { description "March of the Julian and Gregorian calendar"; } enum april { description "April of the Julian and Gregorian calendar"; } enum may { description "May of the Julian and Gregorian calendar"; } enum june { description "June of the Julian and Gregorian calendar"; } enum july { description "July of the Julian and Gregorian calendar"; } enum august { description "August of the Julian and Gregorian calendar"; } Oslebo Expires March 16, 2015 [Page 7] Internet-Draft LMAP Control Data Model September 2014 enum september { description "September of the Julian and Gregorian calendar"; } enum october { description "October of the Julian and Gregorian calendar"; } enum november { description "November of the Julian and Gregorian calendar"; } enum december { description "December of the Julian and Gregorian calendar"; } } description "A type modeling the month in the Julian and Gregorian tradition."; } typedef timezone-offset { type string { pattern "Z|[\+\-]\d{2}:\d{2}"; } description "A timezone-offset as it is use in the yang:date-and-time type. The value Z is equivalent to +00:00. The value -00:00 indicates and unknown time-offset."; } grouping timing-start-end-grouping { description "A grouping that provides start and end times for timing objects."; leaf start { type yang:date-and-time; description "The date and time when the timing object starts to create triggers."; } leaf end { type yang:date-and-time; description "The date and time when the timing object stops to create triggers. It is generally a good idea to always configure an end time and to refresh the configuration of timing object Oslebo Expires March 16, 2015 [Page 8] Internet-Draft LMAP Control Data Model September 2014 as needed to ensure that agents that loose connectivity to their controller do not continue their tasks forever."; } } container lmap-control { description "LMAP Control configuration"; container tasks { description "Task configuration"; list task { key "name"; description "List of available tasks."; leaf name { type string; mandatory "true"; description "The unique name of the task."; } leaf registry-entry { type inet:uri; mandatory "true"; description "Registry URI identifying the task."; } leaf role { type string; description "Measurement Agent role."; } container options { description "Configuration of options passed to the task."; list option { key "name"; description "List of options."; leaf name { type string; description "Option name."; } leaf value { type string; description "Option value."; Oslebo Expires March 16, 2015 [Page 9] Internet-Draft LMAP Control Data Model September 2014 } } } leaf suppress-by-default { type boolean; default "true"; description "Indicates the behavior of the default suppress instruction for this task. If FALSE then the Task will not be suppressed."; } leaf cycle-id { type string; description "Measurement Cycle ID that can be used to easily identify a set of measurement results. The ID should be incremented or changed when a task option is changed so that two sets of results can no longer be directly compared."; } } } container channels { description "Channel configuration"; list channel { key "name"; description "The list of available channels"; leaf name { type string; description "The unique name of the channel"; } leaf target { type inet:uri; mandatory "true"; description "The remote endpoint of the channel."; } leaf credentials { type string; mandatory "true"; description "The security credentials to establish a secure channel."; } leaf interface-name { Oslebo Expires March 16, 2015 [Page 10] Internet-Draft LMAP Control Data Model September 2014 type leafref { path "/if:interfaces/if:interface/if:name"; } description "Name of interface to use when MA has multiple interfaces."; } } } container schedules { description "Schedules configuration"; list schedule { key "name"; description "The list of available schedules."; leaf name { type string; description "The unique name of the schedule."; } container tasks { description "The configuration of tasks that are executed as part of this schedule."; list task { key "name"; description "The list of the tasks."; leaf name { type leafref { path "/lmap-control/tasks/task/name"; } description "The reference to a named task that will be executed"; } container channels { description "Configuration of channels used by the task."; leaf-list channel { type leafref { path "/lmap-control/channels/channel/name"; } description "List of channels used by the task."; } } Oslebo Expires March 16, 2015 [Page 11] Internet-Draft LMAP Control Data Model September 2014 container downstream-schedules { description "Configuration of downstream schedules. The output from this task is sendt to all tasks inside this schedule."; list downstream-schedule { key "schedule"; description ""; leaf schedule { type leafref { path "/lmap-control/schedules/schedule/name"; } description "The list of downstream schedules."; } container outputs { description "Configuration of task outputs"; leaf-list output { type int32; description "List of task outputs that will be sendt to this downstream schedule."; } } } } } } leaf timing { type leafref { path "/lmap-control/timings/timing/name"; } description "The timing of the schedule."; } } } container timings { description "Configuration of LMAP timings. Implementations may be forced to delay acting upon triggers in the face of local constraints. A task triggered therefore not rely on the accuracy provided by the scheduler implementation."; list timing { key "name"; description Oslebo Expires March 16, 2015 [Page 12] Internet-Draft LMAP Control Data Model September 2014 "The list of timings configured on the LMAP agent."; leaf name { type string; description "The unique name of a timing."; } choice timing-type { mandatory "true"; description "Different types of timing objects are handled by different branches of this choices."; case periodic { container periodic { description "A periodic timing object triggers periodically driven by a regular interval."; leaf interval { type uint32; units "milliseconds"; mandatory "true"; description "The number of milliseconds between two triggers generated by this periodic timing object. The execution system must not generate triggers for periodic timing objects that have a interval value of 0. A timing object with an interval of 0 milliseconds will therefore never trigger."; } uses timing-start-end-grouping; } } case calendar { container calendar { description "A calendar timing object trigger based on the current calendar date and time."; leaf-list month { type month; description "A month at which this calendar timing will trigger."; } leaf-list weekday { type weekday; description "A weekday at which this calendar timing will trigger."; } Oslebo Expires March 16, 2015 [Page 13] Internet-Draft LMAP Control Data Model September 2014 leaf-list day-of-months { type int8 { range "-31..-1 | 1..31"; } description "A day in the months at which this calendar timing will trigger. Negative numbers indicate days counted backwards from the end of the months."; } leaf-list hour { type int8 { range "0..23"; } description "An hour at which this calendar timing will trigger."; } leaf-list minute { type int8 { range "0..59"; } description "A minute at which this calendar timing will trigger."; } leaf-list second { type int8 { range "0..59"; } description "A second at which this calendar timing will trigger."; } leaf timezone-offset { type timezone-offset; description "The timezone in which this calendar timing object will be evaluated."; } uses timing-start-end-grouping; } } case one-off { leaf one-off-time { type yang:date-and-time; mandatory "true"; description "This one-off timing object triggers once at the Oslebo Expires March 16, 2015 [Page 14] Internet-Draft LMAP Control Data Model September 2014 configured one-off-time."; } } case immediate { leaf immediate { type empty; mandatory "true"; description "This immediate timing object triggers immediately when it is configured."; } } case startup { leaf startup { type empty; mandatory "true"; description "This startup timing object triggers whenever the LMAP agent (re)starts."; } } } leaf random-spread { type int32; units "milliseconds"; description "This optional leaf adds a random spread to the computation of the trigger."; } } } container log { description ""; list log-entry { key "agent-id log-event-time"; description ""; leaf agent-id { type leafref { path "/lmap-control/measurement-agents/ma/agent-id"; } description ""; } leaf log-event-time { type int64; description Oslebo Expires March 16, 2015 [Page 15] Internet-Draft LMAP Control Data Model September 2014 "Timestamp (number of ms since January 1, 1970, 00:00:00 GMT) of the log event"; } leaf log-code { type int32; mandatory true; description ""; } leaf log-description { type string; mandatory true; description ""; } } } container measurement-agents { description "Configuration of Measurement Agents."; list ma { key "agent-id"; description "List of Mesurement Agents that are controlled by a controller."; leaf agent-id { type yang:uuid; mandatory "true"; description "The unique ID of the MA"; } container config { description "Configuration of a Measurement Agent."; leaf device-id { type inet:uri; description "Optional device ID that can be used to identify the MA before an agent ID is assigned."; } leaf credentials { type string; mandatory "true"; description "The credentials of the agent."; } leaf group-id { type string; Oslebo Expires March 16, 2015 [Page 16] Internet-Draft LMAP Control Data Model September 2014 description "Optional group ID of the agent"; } leaf report-id-flag { type boolean; default "false"; description "If true then the agent ID will be reported to the collectors."; } leaf control-channel-failure-threshold { type int32; description ""; } } container schedules { description "Configuration of active schedules for this MA."; leaf-list schedule { type leafref { path "/lmap-control/schedules/schedule/name"; } description "List of active schedules."; } } container suppressions { description "Configuration of suppressions"; leaf enabled { type boolean; default "false"; description "Setting this to true will suppress all tasks where suppress-by-default is true."; } leaf stop-ongoing-tasks { type boolean; default "false"; description "Setting this to true will terminate all running tasks when enabled is also set to true."; } leaf start { type yang:date-and-time; description "The date and time when suppression should start. If Oslebo Expires March 16, 2015 [Page 17] Internet-Draft LMAP Control Data Model September 2014 not present then suppression will start immediately."; } leaf stop { type yang:date-and-time; description "The date and time when suppression should stop. If not present the suppression will continue until 'enabled' is set to false."; } container tasks { description "Configuration of tasks that will be suppressed."; leaf-list task { type leafref { path "/lmap-control/tasks/task/name"; } description "The list of tasks that will be suppressed. If the list is empty, then all tasks will be suppressed."; } } container schedules { description "Configuration of schedules that will be suppressed."; leaf-list schedule { type leafref { path "/lmap-control/schedules/schedule/name"; } description "The list of schedules that will be suppressed. If the list is empyt, then all schedules will be suppressed."; } } } container status-and-capabilities { description "Operational status and capabilities of the measurement agent."; leaf hardware { type string; default "true"; description "A short description of the hardware that the measurement agent is running on."; } leaf firmware { Oslebo Expires March 16, 2015 [Page 18] Internet-Draft LMAP Control Data Model September 2014 type string; description "The firmware version that the measurement agent is running on"; } leaf version { type string; description "The version number of the measurement agent software."; } container interfaces { description "Interfaces available for measurements."; leaf-list interface { type leafref { path "/if:interfaces/if:interface/if:name"; } description "List of interfaces"; } } leaf last-measurement { type yang:date-and-time; description "The date and time of the last performed measurement task."; } leaf last-report { type yang:date-and-time; description "The date and time of the last reporting task."; } leaf last-instruction { type yang:date-and-time; description "The date and time for when the measurement agent last received new instructions."; } leaf last-configuration { type yang:date-and-time; description "The date and time for when the measurement agent last received new configuration data."; } container supported-tasks { description "Supported tasks."; Oslebo Expires March 16, 2015 [Page 19] Internet-Draft LMAP Control Data Model September 2014 list supported-task { key "name"; description "The list of tasks supported by the measurement agent."; leaf name { type string; description "The name of the supported task."; } leaf registry { type inet:uri; mandatory "true"; description "The registry entry of the supported task."; } leaf role { type string; description "The role of the measurement agent in the in the supported task."; } } } container conditions { description ""; list condition { key "code"; description ""; leaf code { type string; description ""; } leaf text { type string; description ""; } } } } } } } } Oslebo Expires March 16, 2015 [Page 20] Internet-Draft LMAP Control Data Model September 2014 4. Security Considerations TBD 5. Acknowledgements Some parts of the YANG model was copied from [I-D.schoenw-lmap-yang]. 6. Normative References [I-D.ietf-lmap-framework] Eardley, P., Morton, A., Bagnulo, M., Burbridge, T., Aitken, P., and A. Akhter, "A framework for large-scale measurement platforms (LMAP)", draft-ietf-lmap- framework-08 (work in progress), August 2014. [I-D.ietf-netconf-restconf] Bierman, A., Bjorklund, M., Watsen, K., and R. Fernando, "RESTCONF Protocol", draft-ietf-netconf-restconf-01 (work in progress), July 2014. [I-D.schoenw-lmap-yang] Schoenwaelder, J. and V. Bajpai, "A YANG Data Model for LMAP Measurement Agents", draft-schoenw-lmap-yang-01 (work in progress), September 2014. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. Appendix A. Example configuration Configuration urn:..:configuration Report urn:..:report Ping urn:ping Control channel http://www.example.com/control Report channel http://www.example.com/report Configuration Configuration Control channel Hourly Ping Ping Report daily 1 Oslebo Expires March 16, 2015 [Page 22] Internet-Draft LMAP Control Data Model September 2014 Hourly Report daily Report Report channel Daily Hourly 60000 Daily 1440000 00000000-0000-0000-0000-000000000001 1 Configuration 00000000-0000-0000-0000-000000000002 1 Oslebo Expires March 16, 2015 [Page 23] Internet-Draft LMAP Control Data Model September 2014 Configuration Ping Appendix B. RESTCONF queries B.1. Get configuration - XML format This example shows how a MA can retrieve the configuration information from the controller in XML format. Note that some lines are wrapped for display purposes only. GET /restconf/data/lmap-control:lmap-control/measurement-agents/ ma=00000000-0000-0000-0000-000000000001/config HTTP/1.1 Host: 127.0.0.1:5000 Accept: application/yang.data+xml, application/yang.errors+xml The server might respond as follows. HTTP/1.0 200 OK Content-Type: application/yang.data+xml Server: example-server Date: Fri, 12 Sep 2014 11:56:42 GMT 1 B.2. Get schedules - JSON format This example shows how a MA can retrieve a list of active schedules from the controller in JSON format. GET /restconf/data/lmap-control:lmap-control/measurement-agents/ ma=00000000-0000-0000-0000-000000000002/schedules HTTP/1.1 Host: 127.0.0.1:5000 Accept: application/yang.data+json, application/yang.errors+json The server might respond as follows. Oslebo Expires March 16, 2015 [Page 24] Internet-Draft LMAP Control Data Model September 2014 HTTP/1.0 200 OK Content-Type: application/yang.data+json Server: example-server Date: Fri, 12 Sep 2014 12:14:15 GMT { "schedules": { "schedule": [ "Configuration", "Ping" ] } } Author's Address Arne Oslebo UNINETT Email: arne.oslebo@uninett.no Oslebo Expires March 16, 2015 [Page 25]